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

1
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
  }
}

1
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

1
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"
    }
  }
}

1
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]

1
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

1
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"
    }
  ]
}

1
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

1
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"
        }
      }
    }
  ]
}

1
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

1
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"
        }
      }
    }
  ]
}

1
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

1
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"
    }
  ]
}

1
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"
  ]
}

1
2
3
4
5
6
7
8
9

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`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

1
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"
    }
  ]
}

1
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"
  ]
}

1
2
3
4
5
6

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`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

1
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"
        }
      }
    }
  ]
}

1
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"
  ]
}

1
2
3
4
5
6

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`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

1
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"
        }
      }
    }
  ]
}

1
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"
  ]
}

1
2
3
4
5
6

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`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

1
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"
    }
  ]
}

1
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"
  ]
}

1
2
3
4
5
6

To delete all entries:

{
  "all": true
}

1
2
3

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`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]

1
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."
    ]
  }
}

1
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"
  ]
}

1
2
3
4
5
6

To delete all entries:

{
  "all": true
}

1
2
3

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`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]

1
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."
    ]
  }
}

1
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"
  ]
}

1
2
3
4
5
6

To delete all entries:

{
  "all": true
}

1
2
3

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`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]

1
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."
    ]
  }
}

1
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"
  ]
}

1
2
3
4
5
6

To delete all entries:

{
  "all": true
}

1
2
3

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`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]

1
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."
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11

See - Validation errors

# Recipients

# Get recipients

# Request parameters

# Responses

# Valid

# Error

# Get a single recipient

# Request parameters

# Responses

# Valid

# Error

# Delete a recipient

# Request parameters

# Responses

# Valid

# Error

# Get recipients from a suppression list

# Blocklist

# Request parameters

# Responses

# Valid

# Error

# Hard Bounces

# Request parameters

# Responses

# Valid

# Error

# Spam Complaints

# Request parameters

# Responses

# Valid

# Error

# Unsubscribes

# Request parameters

# Responses

# Valid

# Error

# Add recipients to a suppression list

# Blocklist

# Request Body

# Request parameters

# Responses

# Valid

# Error

# Hard Bounces

# Request Body

# Request parameters

# Responses

# Valid

# Error

# Spam Complaints

# Request Body

# Request parameters

# Responses

# Valid

# Error

# Unsubscribes

# Request Body

# Request parameters

# Responses

# Valid

# Error

# Delete recipients from a suppression list

# Blocklist

# Request Body

# Request parameters

# Responses

# Valid

# Error

# Hard Bounces

# Request Body

# Request parameters

# Responses

# Valid

# Error

# Spam Complaints

# Request Body

# Request parameters

# Responses

# Valid

Recipients

Get recipients

Request parameters

Responses

Valid

Error

Get a single recipient

Request parameters

Responses

Valid

Error

Delete a recipient

Request parameters

Responses

Valid

Error

Get recipients from a suppression list

Blocklist

Request parameters

Responses

Valid

Error

Hard Bounces

Request parameters

Responses

Valid

Error

Spam Complaints

Request parameters

Responses

Valid

Error

Unsubscribes

Request parameters

Responses

Valid

Error

Add recipients to a suppression list

Blocklist

Request Body

Request parameters

Responses

Valid

Error

Hard Bounces

Request Body

Request parameters

Responses

Valid

Error

Spam Complaints

Request Body

Request parameters

Responses

Valid

Error

Unsubscribes

Request Body

Request parameters

Responses

Valid

Error

Delete recipients from a suppression list

Blocklist

Request Body

Request parameters

Responses

Valid

Error

Hard Bounces

Request Body

Request parameters

Responses

Valid

Error

Spam Complaints

Request Body

Request parameters

Responses

Valid