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. |