General API resources

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

Authentication

Authentication is done by adding an Authorization header containing an API token as a value to your API request.

To do this, you need to add an 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

API response

MailerSend follows the REST architectural style for it's API and conforms to generic HTTP response standards.

HTTP status codes

MailerSend returns standard HTTP response codes.

Code	Name	Explanation
200	OK	The request was accepted.
201	Created	Resource was created.
202	Accepted	The request was accepted and further actions are taken in the background.
204	No Content	The request was accepted and there is no content to return.
400	Bad Request	There was an error when processing your request. Please adjust your request based on the endpoint requirements and try again.
401	Unauthorized	The provided API token is invalid. Read more
403	Forbidden	The action is denied for that account or a particular API token. Please make sure your account is allowed API access and check your API token permissions. Read more
404	Not Found	The requested resource does not exist on the system.
405	Method Not Allowed	HTTP method is not supported by the requested endpoint.
408	Request Timeout	There is an error on our system. Please contact support
421	Service isn't available, try again later	We are currently running maintenance.
422	Unprocessable Entity	There was a validation error found when processing the request. Please adjust it based on the endpoint requirements and try again. Read more
429	Too Many Requests	There were too many requests made to the API. Read more on rate limits and daily request quota.
500	Internal Server Error	There was an error on our system. Please contact support
502	Bad Gateway	There was an error on our system. Please contact support
503	Service Unavailable	There was an error on our system. Please contact support
504	Gateway Timeout	There was an error on our system. Please contact support

More info on HTTP response codes can be found on Mozilla Developer Network.

Validation errors

You might experience some of the errors described below when a request fails to pass validation. The response will return an array that contains the names of fields that failed as a key and an array of strings as a value.

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

Get more information on validation errors in our knowledge base

Rate limits

MailerSend has a default rate limit of 60 requests per minute on general API endpoints. If you exceed that rate limit, you will receive a 429 error response with a “Too Many Attempts.” message. Please wait for the amount of seconds indicated by retry-after and try again.

Request type	Rate limit
All API requests (excluding email endpoints)	60 requests/minute
API requests to POST /v1/email	120 requests/minute
API requests to POST /v1/bulk-email	10 requests/minute
SMTP	120 requests/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."
}

Daily request quota

MailerSend has a daily request quota for API and SMTP relay services. Every request is counted against the quota and is reset daily at midnight UTC.

Plan	Quota / day
No Plan	100
Free	1000
Premium	100,000
Enterprise	500,000

Two HTTP headers to indicate the quota limit and quota reset time will be returned with every API request. When the quota is hit, MailerSend will return a 429 HTTP error.

Example response

HTTP/2 429
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 59
retry-after: 59
x-apiquota-remaining: 0
x-apiquota-reset: 2022-03-05T00:00:00Z

{
    "message": "Daily API quota limit was reached."
}

Tips

• Avoid sending repeated API requests that fail validation (HTTP 422 error)
• To track email activity and status, use webhooks
• If you are sending emails in bulk, use bulk endpoint
• For more throughput, upgrade to a premium plan.

Email resource

Activity status list

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

Status	Description
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 folder.
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.

SMS resource

SMS status list

Status	Description
processed	Our servers have processed your request and your SMS has been passed to our sending servers.
queued	Your API request has been authorized and will be processed.
sent	Your SMS was sent from our sending servers and the downstream carrier has accepted the message.
delivered	MailerSend has received a delivery receipt from the downstream carrier confirming successful delivery to the carrier or handset (when available).
failed	The message could not be sent or the delivery receipt received from the downstream carrier indicated the message was not deliverable. Review error codes for more information.