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 moreopen in new window

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.

CodeNameExplanation
200OKThe request was accepted.
201CreatedResource was created.
202AcceptedThe request was accepted and further actions are taken in the background.
204No ContentThe request was accepted and there is no content to return.
400Bad RequestThere was an error when processing your request. Please adjust your request based on the endpoint requirements and try again.
401UnauthorizedThe provided API token is invalid. Read moreopen in new window
403ForbiddenThe 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 moreopen in new window
404Not FoundThe requested resource does not exist on the system.
405Method Not AllowedHTTP method is not supported by the requested endpoint.
408Request TimeoutThere is an error on our system. Please contact supportopen in new window
421Service isn't available, try again laterWe are currently running maintenance.
422Unprocessable EntityThere was a validation error found when processing the request. Please adjust it based on the endpoint requirements and try again. Read more
429Too Many RequestsThere were too many requests made to the API. Read more on rate limits and daily request quota.
500Internal Server ErrorThere was an error on our system. Please contact supportopen in new window
502Bad GatewayThere was an error on our system. Please contact supportopen in new window
503Service UnavailableThere was an error on our system. Please contact supportopen in new window
504Gateway TimeoutThere was an error on our system. Please contact supportopen in new window

More info on HTTP response codes can be found on Mozilla Developer Networkopen in new window.

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 baseopen in new window

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 typeRate limit
All API requests (excluding email endpoints)60 requests/minute
API requests to POST /v1/email120 requests/minute
API requests to POST /v1/bulk-email10 requests/minute
SMTP120 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.

PlanQuota / day
No Plan100
Free1000
Premium100,000
Enterprise500,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.

StatusDescription
queuedYour API request has been authorized and will be processed.
sentYour email was sent from our sending servers. We are now waiting for a response from the receiving servers.
deliveredYour email was successfully delivered with no errors.
soft_bouncedYour 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_bouncedYour 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.
junkYour message was sent to your recipient’s junk folder.
openedThe recipient received your message and opened it. Opens tracking is only available if you enabled it in your domain settings.
clickedThe recipient clicked a link that’s in your message. Likewise, clicks tracking is only available if you enabled it in your domain settings.
unsubscribedYour message was rejected because the recipient's email address is in your Suppression list.
spam_complaintsSimilarly, your message was rejected because the recipient's email address is in your Suppression list.

SMS resource

SMS status list

StatusDescription
processedOur servers have processed your request and your SMS has been passed to our sending servers.
queuedYour API request has been authorized and will be processed.
sentYour SMS was sent from our sending servers and the downstream carrier has accepted the message.
deliveredMailerSend has received a delivery receipt from the downstream carrier confirming successful delivery to the carrier or handset (when available).
failedThe 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.
Last Updated: