Recipients
Fetch the email addresses of recipients and other relevant information.
Get recipients
Retrieve the email addresses of recipients using this GET
request:
GET https://api.mailersend.com/v1/recipients
Request parameters
Query parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | int | no | ||
page | int | no | ||
limit | int | no | Min: 10 , Max: 100 | Default: 25 |
Responses
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "5ee0b174b251345e407c92dc",
"email": "dsanford@example.net",
"created_at": "2020-06-10 10:09:56",
"updated_at": "2020-06-10 10:09:56",
"deleted_at": ""
},
{
"id": "5ee0b174b251345e407c92dd",
"email": "konopelski.nina@example.com",
"created_at": "2020-06-10 10:09:56",
"updated_at": "2020-06-10 10:09:56",
"deleted_at": ""
},
{
"id": "5ee0b174b251345e407c92de",
"email": "hester.howe@example.net",
"created_at": "2020-06-10 10:09:56",
"updated_at": "2020-06-10 10:09:56",
"deleted_at": ""
}
],
"links": {
"first": "https:\/\/www.mailersend.io\/api\/v1\/recipients?page=1",
"last": "https:\/\/www.mailersend.io\/api\/v1\/recipients?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https:\/\/www.mailersend.io\/api\/v1\/recipients",
"per_page": 25,
"to": 3,
"total": 3
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Get a single recipient
Retrieve the information of a single recipient and its domain using this GET
request:
GET https://api.mailersend.com/v1/recipients/{recipient_id}
Request parameters
URL parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
recipient_id | string |
Responses
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": {
"id": "5ee0b185b251345e407c938e",
"email": "hauck.sincere@example.net",
"created_at": "2020-06-10 10:10:13",
"updated_at": "2020-06-10 10:10:13",
"deleted_at": "",
"emails": [],
"domain": {
"id": "2j6xej",
"name": "example.org",
"dkim": true,
"spf": true,
"mx": false,
"tracking": false,
"is_verified": true,
"is_cname_verified": false,
"is_dns_active": true,
"is_cname_active": false,
"is_tracking_allowed": false,
"has_not_queued_messages": false,
"not_queued_messages_count": 0,
"domain_settings": {
"send_paused": false,
"track_clicks": true,
"track_opens": true,
"track_unsubscribe": true,
"track_unsubscribe_html": "<p>Click here to <a href=\"{$unsubscribe}\">unsubscribe<\/a><\/p>",
"track_unsubscribe_plain": "Click here to unsubscribe: {$unsubscribe}",
"track_content": true,
"custom_tracking_enabled": false,
"custom_tracking_subdomain": "email"
},
"created_at": "2020-06-10 10:10:13",
"updated_at": "2020-06-10 10:10:13"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
Error
Response Code: 404 Not Found
Delete a recipient
Delete the information of a single recipient and its domain using this DELETE
request:
DELETE https://api.mailersend.com/v1/recipients/{recipient_id}
Request parameters
URL parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
recipient_id | string |
Responses
Valid
Response Code: 200 OK
Response Body: [EMPTY]
2
Error
Response Code: 404 Not Found
Get recipients from a suppression list
Blocklist
Retrieve the recipients in a blocklist of an account or domain by passing the blocklist ID with this GET
request:
GET https://api.mailersend.com/v1/suppressions/blocklist
Request parameters
Query parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
limit | int | no | Min: 10 , Max: 100 | Default: 25 |
page | int | no |
Responses
Response key | Type | Details |
---|---|---|
data.* | object[] | Array of recipients in the blocklist. |
data.*.domain | object | Includes data of the domain related to the blocklist. When this property is null , the blocklist is attached to an account instead of a domain. |
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "60f0176881bf3d1fe618daae",
"type": "pattern",
"pattern": ".*@example.net",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "remotecompany.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
},
"created_at": "2021-07-14T07:04:01.298000Z",
"updated_at": "2021-07-14T07:04:01.298000Z"
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Hard Bounces
Retrieve the hard bounced recipients of an account or domain by passing its ID with this GET
request:
GET https://api.mailersend.com/v1/suppressions/hard-bounces
Request parameters
Query parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
limit | int | no | Min: 10 , Max: 100 | Default: 25 |
page | int | no |
Responses
Response key | Type | Details |
---|---|---|
data.* | object[] | Array of hard bounces. |
data.*.recipient | object | Recipient related to the hard bounce. |
data.*.recipient.domain | object | Domain related to the hard bounce. |
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "60f0176881bf3d1fe618dab0",
"reason": "Unknown reason",
"created_at": "2021-06-29T07:04:01.298000Z",
"recipient": {
"id": "60f0176881bf3d1fe618daaf",
"email": "test@example.com",
"created_at": "2021-06-29T07:04:01.298000Z",
"updated_at": "2021-06-29T07:04:01.298000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "remotecompany.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
}
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Spam Complaints
Retrieve the recipients who have made a spam complaint for an account or domain by passing its ID with this GET
request:
GET https://api.mailersend.com/v1/suppressions/spam-complaints
Request parameters
Query parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
limit | int | no | Min: 10 , Max: 100 | Default: 25 |
page | int | no |
Responses
Response key | Type | Details |
---|---|---|
data.* | object[] | Array of spam complaints. |
data.*.recipient | object | Recipient related to the spam complaint. |
data.*.recipient.domain | object | Domain related to the spam complaint. |
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "60f0176981bf3d1fe618dab4",
"created_at": "2021-06-29T07:04:01.298000Z",
"recipient": {
"id": "60f0176881bf3d1fe618dab3",
"email": "pmcdermott@example.net",
"created_at": "2021-06-29T07:04:01.298000Z",
"updated_at": "2021-06-29T07:04:01.298000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "remotecompany.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
}
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Unsubscribes
Retrieve the unsubscribed recipients for an account or domain by passing its ID with this GET
request:
GET https://api.mailersend.com/v1/suppressions/unsubscribes
Request parameters
Query parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
limit | int | no | Min: 10 , Max: 100 | Default: 25 |
page | int | no |
Responses
Response key | Type | Details |
---|---|---|
data.* | object[] | Array of unsubscribes. |
data.*.recipient | object | Recipient related to the unsubscribe. |
data.*.recipient.domain | object | Domain related to the unsubscribe. |
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "60f0176881bf3d1fe618dab2",
"reason": "NEVER_SIGNED",
"readable_reason": "I never signed up for this mailing list",
"recipient": {
"id": "60f0176881bf3d1fe618dab1",
"email": "taya86@example.com",
"created_at": "2021-06-29T07:04:01.298000Z",
"updated_at": "2021-06-29T07:04:01.298000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "remotecompany.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
},
"created_at": "2021-06-29T07:04:01.298000Z"
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Add recipients to a suppression list
Blocklist
Add a recipient to a blocklist with this POST
request:
POST https://api.mailersend.com/v1/suppressions/blocklist
Request Body
{
"domain_id": "83gwk2j7zqz1nxyd",
"recipients": [
"test@example.com"
],
"patterns": [
".*@example.com"
]
}
2
3
4
5
6
7
8
9
Request parameters
JSON parameters are provided in dot notation.
JSON parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
recipients[] | string[] | no | If patterns is not defined, this property is required. | |
recipients.* | string | yes | Must be an email. | |
patterns[] | string[] | no | If recipients is not defined, this property is required. | |
patterns.* | string | yes |
Responses
Response key | Type | Details |
---|---|---|
data.* | object[] | Array of blocklist entries created. |
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "60f198790542d97fb66dfe52",
"type": "exact",
"pattern": "test@example.com",
"created_at": "2021-07-16T14:32:25.457000Z",
"updated_at": "2021-07-16T14:32:25.457000Z"
},
{
"id": "60f198790542d97fb66dfe53",
"type": "pattern",
"pattern": ".*@example.com",
"created_at": "2021-07-16T14:32:25.476000Z",
"updated_at": "2021-07-16T14:32:25.476000Z"
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Hard Bounces
Add a hard bounce for one or more recipients with this POST
request:
POST https://api.mailersend.com/v1/suppressions/hard-bounces
Request Body
{
"domain_id": "83gwk2j7zqz1nxyd",
"recipients": [
"test@example.com"
]
}
2
3
4
5
6
Request parameters
JSON parameters are provided in dot notation.
JSON parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes | ||
recipients[] | string[] | yes | ||
recipients.* | string | yes | Must be an email. |
Responses
Response key | Type | Details |
---|---|---|
data.* | object[] | Array of hard bounces created. |
data.*.recipient | object | Recipient related to the hard bounce. |
data.*.domain.domain | object | Domain related to the hard bounce. |
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "60f1a0195c14080bbc606293",
"reason": null,
"created_at": "2021-07-16T15:04:57.939000Z",
"recipient": {
"id": "60f1a0195c14080bbc606292",
"email": "test@example.com",
"created_at": "2021-07-16T15:04:57.888000Z",
"updated_at": "2021-07-16T15:04:57.907000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "remotecompany.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
}
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Spam Complaints
Add a spam complaint for one or more recipients with this POST
request:
POST https://api.mailersend.com/v1/suppressions/spam-complaints
Request Body
{
"domain_id": "83gwk2j7zqz1nxyd",
"recipients": [
"test@example.com"
]
}
2
3
4
5
6
Request parameters
JSON parameters are provided in dot notation.
JSON parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes | ||
recipients[] | string[] | yes | ||
recipients.* | string | yes | Must be an email. |
Responses
Response key | Type | Details |
---|---|---|
data.* | object[] | Array of spam complaints created. |
data.*.recipient | object | Recipient related to the spam complaint. |
data.*.recipient.domain | object | Domain related to the spam complaint. |
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "60f1a9fa33d68f023f2d3972",
"created_at": "2021-07-16T15:47:06.280000Z",
"recipient": {
"id": "60f1a0195c14080bbc606292",
"email": "test@example.com",
"created_at": "2021-07-16T15:04:57.888000Z",
"updated_at": "2021-07-16T15:47:06.244000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "remotecompany.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
}
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Unsubscribes
Set one or more recipients as unsubscribed with this POST
request:
POST https://api.mailersend.com/v1/suppressions/unsubscribes
Request Body
{
"domain_id": "83gwk2j7zqz1nxyd",
"recipients": [
"test@example.com"
]
}
2
3
4
5
6
Request parameters
JSON parameters are provided in dot notation.
JSON parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes | ||
recipients[] | string[] | yes | ||
recipients.* | string | yes | Must be an email. |
Responses
Response key | Type | Details |
---|---|---|
data.* | object[] | Array of unsubscribe entries created. |
data.*.recipient | object | Recipient related to the unsubscribe. |
data.*.recipient.domain | object | Domain related to the unsubscribe. |
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"data": [
{
"id": "60f53a20506faf239d471ff2",
"reason": null,
"readable_reason": null,
"recipient": {
"id": "60f1a0195c14080bbc606292",
"email": "test@example.com",
"created_at": "2021-07-16T15:04:57.888000Z",
"updated_at": "2021-07-19T08:38:56.243000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "remotecompany.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
},
"created_at": "2021-07-19T08:38:56.283000Z"
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
Delete recipients from a suppression list
Blocklist
Delete one or more blocklist entries with this DELETE
request:
DELETE https://api.mailersend.com/v1/suppressions/blocklist
Request Body
To delete specific entries:
{
"ids": [
"60f198790542d97fb66dfe52",
"60f198790542d97fb66dfe53"
]
}
2
3
4
5
6
To delete all entries:
{
"all": true
}
2
3
Request parameters
JSON parameters are provided in dot notation.
JSON parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
ids | string[] | no | Required if all is not defined. | |
all | boolean | no | Required if ids is not defined. |
Responses
Valid
Response Code: 200 OK
Response Body: [EMPTY]
2
Error
Response Code: 422 Unprocessable Entity
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
2
3
4
5
6
7
8
9
10
11
See - Validation errors
Hard Bounces
Delete one or more hard bounces from recipients by passing the hard bounces IDs with this DELETE
request:
DELETE https://api.mailersend.com/v1/suppressions/hard-bounces
Request Body
To delete specific entries:
{
"ids": [
"60d0563fd4fb3212e2065522",
"60ae0999c3da7c275f3b5589"
]
}
2
3
4
5
6
To delete all entries:
{
"all": true
}
2
3
Request parameters
JSON parameters are provided in dot notation.
JSON parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
ids | string[] | no | Required if all is not defined. | |
all | boolean | no | Required if ids is not defined. |
Responses
Valid
Response Code: 200 OK
Response Body: [EMPTY]
2
Error
Response Code: 422 Unprocessable Entity
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
2
3
4
5
6
7
8
9
10
11
See - Validation errors
Spam Complaints
Delete one or more spam complaints from recipients by providing the spam complaint IDs with this DELETE
request:
DELETE https://api.mailersend.com/v1/suppressions/spam-complaints
Request Body
To delete specific entries:
{
"ids": [
"60d32115d14907786d7fdd42",
"60ae0999c3da7c275f3b558e"
]
}
2
3
4
5
6
To delete all entries:
{
"all": true
}
2
3
Request parameters
JSON parameters are provided in dot notation.
JSON parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
ids | string[] | no | Required if all is not defined. | |
all | boolean | no | Required if ids is not defined. |
Responses
Valid
Response Code: 200 OK
Response Body: [EMPTY]
2
Error
Response Code: 422 Unprocessable Entity
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
2
3
4
5
6
7
8
9
10
11
See - Validation errors
Unsubscribes
Delete one or more unsubscribe entries from recipients by passing the unsubscribe IDs with this DELETE
request:
DELETE https://api.mailersend.com/v1/suppressions/unsubscribes
Request Body
To delete specific entries:
{
"ids": [
"60d3169d8dc7b007f356d142",
"60ae0999c3da7c275f3b558b"
]
}
2
3
4
5
6
To delete all entries:
{
"all": true
}
2
3
Request parameters
JSON parameters are provided in dot notation.
JSON parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
ids | string[] | no | Required if all is not defined. | |
all | boolean | no | Required if ids is not defined. |
Responses
Valid
Response Code: 200 OK
Response Body: [EMPTY]
2
Error
Response Code: 422 Unprocessable Entity
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
2
3
4
5
6
7
8
9
10
11
See - Validation errors