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.

Other error response messages

CodeMessageExplanation
MS40301The custom API token you're using doesn't have the required permissions.The custom API token used doesn't have the required permissions. For example, this error would be returned if youe send a request to the email endpoint using a token that does not allow email access. If you receive this error, check that you are using a token with the required permission.

See more information about token scopes: Possible scopes
MS40302Your account's access to API/SMTP has been switched off.The Customer Support team has switched off the account's API/SMTP access. Please check your account status on the MailerSend app or see if we sent an email with the next steps.
MS40303Your account is not authorized to perform this action.The account tried to send a request to the MailerSend servers but is not authorized to do so. Please check your account status on the MailerSend app or see if we sent an email with the next steps
MS40304Your account is suspended, you can't do any more requests.The account tried to send a request to the MailerSend servers but is suspended. Please check your account status on the MailerSend app or see if we sent an email with the next steps.
MS42201“{recipient email} is duplicated in the {$field} recipients list.”The request contains duplicated recipients. Turn on your domain's Ignore duplicated recipients advanced setting to avoid this error.

Find out more about this setting: What is a sending domainopen in new window
MS42202Could not validate the attached file. Filename and attached file does not match.The file name and file type do not match. For example, the filetype is a GIF file but the file name is image.png.
MS42203There are duplicates in the {$field} recipients list.The request contains duplicated recipients. Turn on your domain's Ignore duplicated recipients advanced setting to avoid this error.

Find out more about this setting: What is a sending domainopen in new window
MS42204Your account reached its email quota limit. Contact support to increase it.The account has a custom email quota due to compliance concerns and it reached it. Contact customer support to clarify how your business uses MailerSend.
MS42205The {$field} recipient limit is exceeded.The limit of TO, CC or BCC recipients in a single email object has been reached. Approved accounts can include up to 50 TO, 10 CC and 10 BCC recipients. Unapproved acounts can include up to 10 TO, 1 CC and 1 BCC recipients. Get your account approved to send to more recipients or use our bulk email endpoint.

See the request parameter of the /email endpoint: Request parameters
MS42206The attachments.0.content size exceeds the threshold of 25 MB.”The attachment size exceeds the limit of 25MB. Zip the file or use a cloud storage service to send your file.

See more information about the list of all supported filetypes: Supported file types
MS42207The from.email domain must be verified in your account to send emails.The from.email domain must be verified in your account to be able to send emails. Please make sure the domain you want to send from has a is_verified value set to 'true' via the API or the app. Premium plan users can also add the from email address as a sender identity.

See more information about verifying your domain: How to verify and authenticate a sending domainopen in new window
MS42208The {$field} must be a valid email address.There was a formatting problem in your request. The to/from/cc/bcc/reply-to.email must be a valid email address.

See more information about the request parameters: Request parameters
MS42209The {$field} field is required.”There was either a formatting problem in your request or you're missing one of the following parameters: to, from, subject.

See more information about the request parameters: Request parameters
MS42210This file type is not supported.”This file type is not supported.

See more information about the list of all supported filetypes: Supported file types
MS42211You must provide one of html, text or template_id.”There was either a formatting problem in your request or you're missing one of the following parameters: html, text or template_id. See more information about request parameters: Request parameters
MS42212The recipient domain {$domain} must be one of the verified domains.The from.email domain must be verified in your account to be able to send emails. Please make sure the domain you want to send from has a is_verified value set to 'true' via the API or the app. Premium plan users can also add the from email address as a sender identity.

See more information about verifying your domain: How to verify and authenticate a sending domainopen in new window
MS42213The value you provided in :attribute failed to compile. Please check the submitted text/html.There are some errors in the text or HTML provided, please make sure there are no errors to avoid conflicts.
MS42214You have used an app reserved variable. Please use another variableThe email you're trying to send has one or more variables that are reserved by the MailerSend application. Please consider changing the variables to avoid conflicts.
MS42215The attachment content must be a Base64 encoded string.All attachments have to be encoded in a Base64 string. Find an encoder to convert your file before attaching it to your email.
MS42216This feature is only available for free and premium users. Upgrade to use it.There are some limits to each plan and the action you'd like to do is not available on your current plan. Please take a look at the current limits and consider upgrading to a higher plan.

See more information about the plan limits: Pricingopen in new window
MS42217One or more emails in the variables field do not exist in the recipients field.The email addresses on the recipient and personalization fields do not match, please make sure you're adding the same email address on both the TO and personalization fields.
MS42218The send_at timestamp does not match the Unix formatThe timestamp used for the send_at parameter is not written in the Unix format. The send_at parameter has to be written in Unix format and be no longer than 72 hours in the future from the moment the call is made.

Use unixtimestampopen in new window to convert a date to the Unix timestamp format.
MS42219The send_at must be a date in the future.The timestamp used for the send_at parameter is not in the future. The send_at parameter has to be written in Unix format and be no longer than 72 hours in the future from the moment the call is made.
MS42901Your account reached its API daily quota limit. Upgrade to increase it.The account making the request reached its API daily quota limit. Upgrade to raise your quota.
Every request is counted against the quota and the quota is reset daily at midnight UTC.

No plan accounts have a daily limit of 100 API requests. Free plan accounts are limited to 1,000 daily requests. Premium plans can send up to 100,000 daily requests, and Enterprise plans can send 100,000+.

See more information about quotas and learn how to avoid this error: Daily request quota
MS42903Your account reached its rate limit of 120 requests/min. Please wait before trying again.The account making the request reached its rate limit. The default rate limit is 120 requests per minute for /email and /bulk-email endpoints and 60 requests per minute for all other endpoints. Please wait for the amount of seconds indicated by 'retry-after' and try again.

See more information about rate limits: Rate limits

SMS delivery codes

CodeDescriptionFriendly DescriptionExplanation Of ErrorBillable
4001service-not-allowedMessage was rejected for reasons other than those covered by other 4xxx codesThis is a general error that the service you are attempting to use is not allowed; you may have inaccurate permissions, formatting or may not be enable to use that service.NO
4301malformed-invalid-encodingMalformed message encodingThe message contains invalid characters that are not supported. MailerSend cannot re-encode message for destination.NO
4302malformed-invalid-from-numberMalformed From numberThe From number associated with the message is a number not routable to a carrier or valid in the industry (Ex: a 9 digit number).NO
4303malformed-invalid-to-numberMalformed To NumberThe To number associated with the message is a number not routable to a carrier or valid in the industry (Ex: a 9 digit number).NO
4350malformed-for-destinationMalformed message encodingMessage passed validation on receive stage, but failed on send. This is likely because the destination number (To) is an invalid number.NO
4360message-not-sent-expiration-date-passedMessage expiredMessage was not sent because the specified expiration date passed before the message was able to sendNO
4401rejected-routing-errorBW is unable to route the messageMessage is unable to be routed within MailerSend particularly when the source and destination are the same number. The destination or To number is mis-provisioned or there is a configuration with the message that is causing a situation where a message is being sent repeatedly between the same numbers.NO
4403rejected-forbidden-from-numberMessaging forbidden on From numberMessaging on this From number is forbidden most commonly because the number does not belong to MailerSend or the account. Other reasons include: the TN is not enabled in the MailerSend Dashboard, the account associated with this number is not enabled for this type of messaging, the TN is disconnected, or it is an invalid number (i.e., 11111111111).NO
4404rejected-forbidden-to-numberMessaging forbidden on To numberMessaging on this To number is forbidden. This could be the number is not active, not enabled for messaging or is an invalid number (i.e. 11111111111)NO
4405rejected-unallocated-from-numberUnallocated from numberThe From telephone number is considered unallocated when the number does not exist in our database as an active number. This number is either not enabled for messaging at the industry level, or the number is not yet released in the industryNO
4406rejected-unallocated-to-numberUnallocated to numberThe To number associated with this message, while a valid North American number, is not yet assigned to a carrier and the message cannot be sent downstream.NO
4407rejected-account-not-defined-from-numberFrom Number is associated with accountUndefined source account id. The From number associated with this message is not associated with this account, is an invalid number or not configured appropriately to send messages.NO
4408rejected-account-not-defined-to-numberTo Number not associated with accountUndefined destination account id. The To (destination) number is not associated with an account, is an invalid number or not configured correctly to receive messages.NO
4409rejected-invalid-from-profileInvalid destination profileMailerSend failed to create destination. The destination profile is considered invalid, most often this is because the destination number does not support MMS.NO
4410media-unavailableCould not download mediaThere was an error retrieving the media from the media web server. Check the media URL and try to access directly to see if the media can be fetched successfully.NO
4411rejected-message-size-limit-exceededCombined size of media too largeThe total size of MMS message media/attachments exceeded the max file size supportedNO
4412media-content-invalidFailed to parse Content-Type for mediaThe media content type is not a supported media content type.NO
4420rejected-carrier-does-not-existNo Route to Destination CarrierThe upstream carrier associated with the message does not exist in MailerSend configurationNO
4421rejected-forbidden-no-destinationNo Route to Destination CarrierThe message cannot be sent downstream as the account associated with the message does not have permission to send to this destination. You may not be provisioned to send to this destination.NO
4432rejected-forbidden-countryMessaging to country forbiddenMailerSend system indicates the account associated with the message is not enabled for messaging this zone, this country or this country is outside of messaging reach (specifically for MMS).NO
4433rejected-forbidden-tollfreeMessaging on Toll Free Number ForbiddenThe account associated with this message is not enabled for toll free messagingNO
4434rejected-forbidden-tollfree-for-recipientMessaging to Toll Free Number ForbiddenMessaging to this toll free number is not allowed. Number is likely not enabled for messaging or not active.NO
4470rejected-spam-detectedRejected as SPAMThis message has been filtered and blocked by MailerSend for spam. Messages can be blocked for a variety of reason, including but not limited to volumetric filtering, content blocking, SHAFT violation, etc.YES
4481rejected-from-number-in-blacklistFrom Number in black listThe From number has been flagged by MailerSend as prohibited from sending messages. This is typically because MailerSend or a downstream carriers has several violations; reports of spam, P2P violations, associated with this number.NO
4482rejected-to-number-in-blacklistTo Number in black listThe number you are attempting to send to is blocked from receiving messages.NO
4492reject-emergencyMessage to emergency number forbiddenMessaging to an emergency number is forbiddenNO
4493rejected-unauthorizedUnauthorizedMailerSend service indicates the sender is not authorized to send messages from the account.NO
4700invalid-service-typeCarrier Rejected as Invalid Service TypeCarrier rejected message for invalid service type. This usually means messaging (SMS or MMS) is not supported by the carrier or handset.YES
4701destination-service-unavailableDestination is not reachable and SMS service is not available.Carrier service is reporting the destination is not reachable or the SMS service is not available.YES
4702destination-subscriber-unavailableDestination subscriber is unavailable.This error indicates the subscriber is unavailable. There are several reasons for this; the subscriber has turned off handset, the destination is unreachable or barred, the GSM subscriber is busy for outbound SMS, SIM card is full, voicemail is full, or cannot reach the destination handset and has stored the message for retry in its « Store & Forward » function.YES
4711rejected-message-size-limit-exceededMedia size too largeDownstream vendor cannot retrieve the media as the MMS attachment is too largeYES
4712media-content-invalidThe media content type is not supportedThe media content type is not supported.YES
4720invalid-destination-addressCarrier Rejected as Invalid Destination AddressCarrier Rejected as Invalid Destination Address. This could mean the number is not in the numbering plan (area code does not exist or the number is just invalid) or the number is not enabled for messaging (like a landline). Additionally, for toll free messages to TMobile, this could also mean the user has opted to block all toll free and short code trafficYES
4721destination-tn-deactivatedTN on deactivation listThe phone number you are attempting to send to is on the deactivation list. It is not associated with a carrier to be able to receive messages or is inactive.YES
4730no-route-to-destination-carrierNo route to destination carrier or no roaming route exists.Carrier is reporting there is no route available for message. This could be because no routing exists to destination, no roaming route is available, the destination handset is roaming on a network that cannot be reached, no SS7 route, or routing was deniedYES
4740invalid-source-address-addressCarrier Rejected as Invalid Source AddressCarrier is rejecting the message due to invalid source address - the number does not exist in the numbering plan. Other reasons for this error code is the source carrier is invalid or disabled or source not authorized or the number type is not supported.YES
4750destination-rejected-messageCarrier Rejected MessageThe destination carrier has rejected the message but provided no specific reason. For AT&T traffic, this could be a prepaid user whose account is out of money, a subscriber that is provisioned to not receive this type of SMS or it was identified as SpamYES
4751destination-rejected-message-size-invalidMessage is too long or message length is invalid for the carrier.Carrier has rejected for message length is invalid or too long.YES
4752destination-rejected-malformedMessage is malformed for the carrier.Carrier is rejecting the message malformed; this could be because of a blank message, unacceptable data value, the receiving SMSC or SME does not accept messages with more than 160 characters, syntax error, content is invalid, message ID is invalid, invalid parameter length, expected TLV missing, invalid TLV value, invalid data coding scheme, invalid number of destinations, error in the optional part of the PDU body, TLV not allowed, or XML validation error.YES
4753destination-rejected-handsetThe destination handset has rejected the messageThe handset has rejected the messageYES
4770destination-spam-detectedCarrier Rejected as SPAMThe Carrier is reporting this message as blocked for SPAM. Spam blocks could be a result of content, SHAFT violations (including specific keywords), originating address has been flagged for repeated spam contentYES
4771rejected-shortened-urlRejected due to shortened urlThere was an error with the shortened URL used. MailerSend recommends customers obtain their own dedicated domain if shortened links are needed for their messaging campaign.YES
4772rejected-tn-blockedBlocked sender or receiverThis error indicates a blocked Sender or Receiver on the downstream platform. Please reach out to MailerSend support so we can determine which telephone number is blocked and why.YES
4775destination-rejected-due-to-user-opt-outCarrier Rejected due to user opt outUser has opted out of receiving messages from a particular sender. Remove the destination TN from subscriber list and cease communication with the destination.YES
4781volume-violation-attAT&T rejected due to 10DLC volumetric violation or throttlingAT&T rejected due to volumetric violation. You have sent over the rate limit for your toll-free number. Please review your number throughput limit to ensure you are not exceeding the approved volumes. This error can also indicate throttling by AT&T for other reasons, including high spam rates.YES
4785volumetric-violationCarrier rejected due to volumetric violationThe carrier rejected the message due to a volumetric violation. You have sent over the allotted limit and need to back off sending. Please retry after some time.YES
4795tfn-not-verifiedToll Free number is not verifiedThe message was blocked due to the toll free number not being verified. This can also be because there is SPAM on the unverified TFN. Please review unverified sending limitsopen in new window and submit TFN for verification as soon as possible.YES
5100temporary-app-errorApplication ErrorAn application within the MailerSend service is experiencing a temporary error that is preventing the message from being processed.NO
5101temporary-app-shutdownApplication ErrorApp going down. Message not received. Sender should send this messages later or to other host.NO
5106impossible-to-routeImpossible to route / Attempt to deliver through retries has failed.Impossible to route / Attempt to deliver through retries has failed.NO
5111temporary-app-connection-closedApplication ErrorReceived messaged for connection which is already removed.NO
5201temporary-rout-error-retries-exceededApplication ErrorMailerSend service expired the message after attempts to deliver through retries failed.NO
5211temporary-app-error-app-busyApplication ErrorMailerSend service application is temporarily busy so it cannot receive messages at this timeNO
5220temporary-store-errorApplication ErrorMessage not received. Cannot save message to store.NO
5231discarded-concatenation-timeoutApplication ErrorMailerSend did not receive all parts of message. Message can not be sent.NO
5500message-send-failedGeneral Message Send FailureThe destination carrier has reported a general service failure with sending the message.NO
5501message-send-failedGeneral Message Send FailureThe message is unable to send as no destination is available.NO
5600destination-carrier-queue-fullCarrier Service UnavailableCarrier Service Unavailable. This could result from network congestion, messaging queue full on the vendor side, throttling error on the vendor side.YES
5610submit _ sm-or-submit _ multi-failedCarrier Service FailureThe downstream carrier application is experiencing an error. submitting the message has failed or cancelling message has failedYES
5620destination-app-errorCarrier Application ErrorThe carrier is reporting a general error associated with their application processing the message.YES
5630message-not-acknowleCarrier Application ErrorNACK - no response or acknowledgement received from the carrierYES
5650destination-failedCarrier Service FailureCarrier Service is reporting a failure to send to destination (mobile operator or handset).YES
5999unknown-errorUnknown error from MailerSendUnknown error generated by MailerSend when MailerSend core reports an unknown errorNO
9902delivery-receipt-expiredTimed out waiting for delivery receipt. The reason a delivery receipt was not received is not known.MailerSend timed out waiting for the delivery receipt, this could be because the downstream provider did not send the requested delivery receipt or they sent after the system timed out at two hours.YES
9999unknown-errorUnknown error from downstream. Carrier reported a failure code that is unknown to MailerSend.MailerSend does not recognize the vendor's error response or does not have the vendor code mapped internallyYES

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 domain must be verified in your account to send emails. #MS42207"
    ]
  }
}

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
API requests to GET /v1/activity10 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": "Your account reached its rate limit of 120 requests/min. Please wait before trying again. #MS42903"
}

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": "Your account reached its API daily quota limit. Upgrade to increase it. #MS42901"
}
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: