General API resources

Here you’ll be able to find all the information about the endpoints’ authorizations, possible statuses of your emails, and validation errors.

Authentication

Authentication is done by adding an Authorization header to your API request that contains an API token.

In order to use the API token, it needs to be added as Authorization header with the contents of the header being Bearer XXX where XXX is your API token.

Authorization: Bearer XXX

API tokens are generated for sending domains and can have different permissions to limit which areas of your account they may be used to access. Read more

Rate limits

MailerSend has a default rate limit of 60 requests/minute on general API endpoints. If you exceed that rate limit you will receive a 429 error response with a “Too Many Attempts.” message.

Request type	Rate limit
All API requests (excluding email endpoints)	60 requests per minute
API requests to POST /v1/email	120 requests per minute
API requests to POST /v1/bulk-email	10 requests per minute
SMTP	120 requests per minute

Example response

HTTP/2 429
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 0
retry-after: 59
x-ratelimit-reset: 1629291024

{
    "message": "Too Many Attempts."
}

Possible statuses

You can query the status of a sent email using the GET request with the ID of the email sent.

Activity status list

Status	Description
processed	Our servers have processed your request and your email has been passed to our sending servers.
queued	Your API request has been authorized and will be processed.
sent	Your email was sent from our sending servers. We are now waiting for a response from the receiving servers.
delivered	Your email was successfully delivered with no errors.
soft_bounced	Your email was not delivered because it soft bounced. A soft bounce is a temporary rejection by a receiving recipient’s server. This may happen because the recipient's inbox is full.
hard_bounced	Your message was not delivered. The message was returned to our servers because the recipient's address is invalid. A hard bounce may occur because the domain name does not exist or because the recipient is unknown. You will not be able to send future email messages to recipients that hard bounced. Use the Suppressions tool to check and manage all rejected recipients.
junk	Your message was sent to your recipient’s junk file.
opened	The recipient received your message and opened it. Opens tracking is only available if you enabled it in your domain settings.
clicked	The recipient clicked a link that’s in your message. Likewise, clicks tracking is only available if you enabled it in your domain settings.
unsubscribed	Your message was rejected because the recipient's email address is in your Suppression list.
spam_complaints	Similarly, your message was rejected because the recipient's email address is in your Suppression list.

Validation errors

You might experience some of the errors described below when authorization fails.

Response Code: 422 Unprocessable Entity
Response Headers:
	Content-Type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "from.email": [
      "The from.email must be verified."
    ]
  }
}