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.

Other error response messages

Code	Message	Explanation
MS40001	The bulk request sent is malformed.	The request payload provided is malformed. Please check the payload and contact Customer Support for more help.
MS40301	The 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
MS40302	Your 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.
MS40303	Your 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
MS40304	Your 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.
MS40305	Your IP address is not allowlisted.	The account tried to send a request to the MailerSend servers from an IP address that is not allowlisted. Please ensure that your IP address is added to the allowlist. You can update your allowlisted IP addresses in the MailerSend app or contact Customer Support for further assistance.
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 domain
MS42202	Could 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.
MS42204	Your 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.
MS42205	The {$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
MS42206	The 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
MS42207	The 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. Users on Starter plans and above 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 domain
MS42208	The {$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
MS42209	The {$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
MS42210	This file type is not supported.”	This file type is not supported. See more information about the list of all supported filetypes: Supported file types
MS42211	You 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
MS42212	The 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. Users on Starter plans and above 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 domain
MS42213	The 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.
MS42214	You have used an app reserved variable. Please use another variable	The 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.
MS42215	The 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.
MS42216	This feature requires a Hobby plan or higher. 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: Pricing
MS42217	One 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.
MS42218	The send_at timestamp does not match the Unix format	The 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 unixtimestamp to convert a date to the Unix timestamp format.
MS42219	The 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.
MS42220	The {$field} may only contain alphanumeric characters and hyphens.	The value submitted must be a string consisting of only alphanumeric characters and hyphens.
MS42221	The {$field} must be a string.	The value submitted must be a string
MS42222	Your trial domain reached its email quota limit.	The email quota limit for your trial domain was reached.
MS42223	You already have a trial account.
MS42224	Templates require a read own templates permission.	The read own templates permission must be assigned to the user in order to allow the user to read the templates provided.
MS42225	You have reached the trial domain unique recipients limit.	Each trial domain has a limit of unique recipients allowed to send an email to. This limit has been reached, and to continue sending emails please use the already created recipients.
MS42226	Your default template domain must be verified in your account to send emails.	The template in use has an associated default domain that is not verified. To send emails the domain must be verified or disassociated from the template.
MS42227	JSON contains a syntax error.	The request payload provided contains a JSON syntax error. Please check the payload and contact Customer Support for more help.
MS42228	JSON contains a decoding error.	The request payload provided contains a decoding error. Please check the payload and contact Customer Support for more help.
MS42229	The number of email objects must not be greater than 500.	The request payload provided contains a number of email objects surpassing the limit of 500.
MS42230	The email objects are required.	The request payload provided does not contain any email object. Please check the payload and contact Customer Support for more help.
MS42231	The bulk request item is invalid.	The email object provided is invalid. Please check the payload and contact Customer Support for more help.
MS42232	The {$field} field is required when role is custom user.	When the user in question has the custom user role, it's mandatory to provide the permission details for that user.
MS42901	Your 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. Trial plan accounts have a daily limit of 100 API requests. Hobby plan accounts are limited to 1,000 daily requests. Starter plan accounts can send up to 100,000 daily requests, and Professional or Enterprise plan accounts can send up to 500,000 requests. See more information about quotas and learn how to avoid this error: Daily request quota
MS42903	Your account reached its rate limit of {$limit} 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 endpoints, 10 requests per minute for /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
MS5001	Something unexpected happened while processing the bulk request. Please contact Customer Support if the problem persists.	An unexpected error occurred in our servers while processing your bulk request. We are aware it happened and are working on finding a fix. Please contact Customer Support if the problem persists.

SMS delivery codes

Code	Description	Friendly Description	Explanation Of Error	Billable
4001	service-not-allowed	Message was rejected for reasons other than those covered by other 4xxx codes	This 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
4301	malformed-invalid-encoding	Malformed message encoding	The message contains invalid characters that are not supported. MailerSend cannot re-encode message for destination.	NO
4302	malformed-invalid-from-number	Malformed From number	The 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
4303	malformed-invalid-to-number	Malformed To Number	The 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
4350	malformed-for-destination	Malformed message encoding	Message passed validation on receive stage, but failed on send. This is likely because the destination number (To) is an invalid number.	NO
4360	message-not-sent-expiration-date-passed	Message expired	Message was not sent because the specified expiration date passed before the message was able to send	NO
4401	rejected-routing-error	BW is unable to route the message	Message 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
4403	rejected-forbidden-from-number	Messaging forbidden on From number	Messaging 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
4404	rejected-forbidden-to-number	Messaging forbidden on To number	Messaging 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
4405	rejected-unallocated-from-number	Unallocated from number	The 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 industry	NO
4406	rejected-unallocated-to-number	Unallocated to number	The 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
4407	rejected-account-not-defined-from-number	From Number is associated with account	Undefined 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
4408	rejected-account-not-defined-to-number	To Number not associated with account	Undefined 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
4409	rejected-invalid-from-profile	Invalid destination profile	MailerSend failed to create destination. The destination profile is considered invalid, most often this is because the destination number does not support MMS.	NO
4410	media-unavailable	Could not download media	There 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
4411	rejected-message-size-limit-exceeded	Combined size of media too large	The total size of MMS message media/attachments exceeded the max file size supported	NO
4412	media-content-invalid	Failed to parse Content-Type for media	The media content type is not a supported media content type.	NO
4420	rejected-carrier-does-not-exist	No Route to Destination Carrier	The upstream carrier associated with the message does not exist in MailerSend configuration	NO
4421	rejected-forbidden-no-destination	No Route to Destination Carrier	The 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
4432	rejected-forbidden-country	Messaging to country forbidden	MailerSend 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
4433	rejected-forbidden-tollfree	Messaging on Toll Free Number Forbidden	The account associated with this message is not enabled for toll free messaging	NO
4434	rejected-forbidden-tollfree-for-recipient	Messaging to Toll Free Number Forbidden	Messaging to this toll free number is not allowed. Number is likely not enabled for messaging or not active.	NO
4470	rejected-spam-detected	Rejected as SPAM	This 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
4481	rejected-from-number-in-blacklist	From Number in black list	The 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
4482	rejected-to-number-in-blacklist	To Number in black list	The number you are attempting to send to is blocked from receiving messages.	NO
4492	reject-emergency	Message to emergency number forbidden	Messaging to an emergency number is forbidden	NO
4493	rejected-unauthorized	Unauthorized	MailerSend service indicates the sender is not authorized to send messages from the account.	NO
4700	invalid-service-type	Carrier Rejected as Invalid Service Type	Carrier rejected message for invalid service type. This usually means messaging (SMS or MMS) is not supported by the carrier or handset.	YES
4701	destination-service-unavailable	Destination 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
4702	destination-subscriber-unavailable	Destination 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
4711	rejected-message-size-limit-exceeded	Media size too large	Downstream vendor cannot retrieve the media as the MMS attachment is too large	YES
4712	media-content-invalid	The media content type is not supported	The media content type is not supported.	YES
4720	invalid-destination-address	Carrier Rejected as Invalid Destination Address	Carrier 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 traffic	YES
4721	destination-tn-deactivated	TN on deactivation list	The 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
4730	no-route-to-destination-carrier	No 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 denied	YES
4740	invalid-source-address-address	Carrier Rejected as Invalid Source Address	Carrier 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
4750	destination-rejected-message	Carrier Rejected Message	The 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 Spam	YES
4751	destination-rejected-message-size-invalid	Message is too long or message length is invalid for the carrier.	Carrier has rejected for message length is invalid or too long.	YES
4752	destination-rejected-malformed	Message 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
4753	destination-rejected-handset	The destination handset has rejected the message	The handset has rejected the message	YES
4770	destination-spam-detected	Carrier Rejected as SPAM	The 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 content	YES
4771	rejected-shortened-url	Rejected due to shortened url	There 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
4772	rejected-tn-blocked	Blocked sender or receiver	This 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
4775	destination-rejected-due-to-user-opt-out	Carrier Rejected due to user opt out	User has opted out of receiving messages from a particular sender. Remove the destination TN from subscriber list and cease communication with the destination.	YES
4781	volume-violation-att	AT&T rejected due to 10DLC volumetric violation or throttling	AT&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
4785	volumetric-violation	Carrier rejected due to volumetric violation	The 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
4795	tfn-not-verified	Toll Free number is not verified	The 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 limits and submit TFN for verification as soon as possible.	YES
5100	temporary-app-error	Application Error	An application within the MailerSend service is experiencing a temporary error that is preventing the message from being processed.	NO
5101	temporary-app-shutdown	Application Error	App going down. Message not received. Sender should send this messages later or to other host.	NO
5106	impossible-to-route	Impossible to route / Attempt to deliver through retries has failed.	Impossible to route / Attempt to deliver through retries has failed.	NO
5111	temporary-app-connection-closed	Application Error	Received messaged for connection which is already removed.	NO
5201	temporary-rout-error-retries-exceeded	Application Error	MailerSend service expired the message after attempts to deliver through retries failed.	NO
5211	temporary-app-error-app-busy	Application Error	MailerSend service application is temporarily busy so it cannot receive messages at this time	NO
5220	temporary-store-error	Application Error	Message not received. Cannot save message to store.	NO
5231	discarded-concatenation-timeout	Application Error	MailerSend did not receive all parts of message. Message can not be sent.	NO
5500	message-send-failed	General Message Send Failure	The destination carrier has reported a general service failure with sending the message.	NO
5501	message-send-failed	General Message Send Failure	The message is unable to send as no destination is available.	NO
5600	destination-carrier-queue-full	Carrier Service Unavailable	Carrier Service Unavailable. This could result from network congestion, messaging queue full on the vendor side, throttling error on the vendor side.	YES
5610	submit _ sm-or-submit _ multi-failed	Carrier Service Failure	The downstream carrier application is experiencing an error. submitting the message has failed or cancelling message has failed	YES
5620	destination-app-error	Carrier Application Error	The carrier is reporting a general error associated with their application processing the message.	YES
5630	message-not-acknowle	Carrier Application Error	NACK - no response or acknowledgement received from the carrier	YES
5650	destination-failed	Carrier Service Failure	Carrier Service is reporting a failure to send to destination (mobile operator or handset).	YES
5999	unknown-error	Unknown error from MailerSend	Unknown error generated by MailerSend when MailerSend core reports an unknown error	NO
9902	delivery-receipt-expired	Timed 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
9999	unknown-error	Unknown 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 internally	YES

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 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
API requests to GET /v1/activity	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": "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.

Plan	Quota / day
Trial	100
Hobby	1000
Starter	100,000
Professional	500,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": "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 professional 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.