MailerSend Developers

# Recipients

# Get recipients

Get the emails 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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations errors

# Get a single recipient

Get the information of a 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

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

# Error

Response Code: 404 Not Found

# Delete a recipient

Delete the information of a 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]

# Error

Response Code: 404 Not Found

# Get recipients from a suppression list

# Blocklist

Get 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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations errors

# Hard Bounces

Get 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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations errors

# Spam Complaints

Get the recipients who have spam complained of 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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations errors

# Unsubscribes

Get the recipients set as unsubscribed of 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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations 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"
  ]
}

# 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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations errors

# Hard Bounces

Add a hard bounced 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"
  ]
}

# Request parameters

JSON parameters are provided in dot notation

JSON parameter Type Required Limitations Details
domain_id string no
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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations 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"
  ]
}

# Request parameters

JSON parameters are provided in dot notation

JSON parameter Type Required Limitations Details
domain_id string no
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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations 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"
  ]
}

# Request parameters

JSON parameters are provided in dot notation

JSON parameter Type Required Limitations Details
domain_id string no
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

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

# Error

Response Code: 422 Unprocessable Entity

See - Validations 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"
  ]
}

To delete all entries:

{
  "all": true
}

# Request parameters

JSON parameters are provided in dot notation

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

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

See - Validations 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"
  ]
}

To delete all entries:

{
  "all": true
}

# Request parameters

JSON parameters are provided in dot notation

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

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

See - Validations errors

# Spam Complaints

Delete one or more spam complaints from recipients by providing the spam complaints ids, with this DELETE request:

DELETE https://api.mailersend.com/v1/suppressions/spam-complaints

# Request Body

To delete specific entries:

{
  "ids": [
    "60d32115d14907786d7fdd42",
    "60ae0999c3da7c275f3b558e"
  ]
}

To delete all entries:

{
  "all": true
}

# Request parameters

JSON parameters are provided in dot notation

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

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

See - Validations errors

# Unsubscribes

Delete one or more unsubscribe entries from recipients by passing the unsubscribes ids, with this DELETE request:

DELETE https://api.mailersend.com/v1/suppressions/unsubscribes

# Request Body

To delete specific entries:

{
  "ids": [
    "60d3169d8dc7b007f356d142",
    "60ae0999c3da7c275f3b558b"
  ]
}

To delete all entries:

{
  "all": true
}

# Request parameters

JSON parameters are provided in dot notation

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

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

See - Validations errors

Last updated: 9/1/2021, 3:08:20 PM

← Templates →