REST API response codes

Status code

Description

200 - OK

Good news! The request is formatted correctly and the requested action should be taken/data returned. This is the positive response for most PUT, GET, and some POST requests in the API documentation.

201 - Created

This means there were no issues found with the request and the requested action has been taken. The 201 response will appear on some API requests, such as successful POST requests to our webhooks and inbound routes endpoints.

202 - Accepted

Hurrah! This response is associated with our email and bulk-email endpoints and means there were no issues found with the request and the email has been queued for sending.

202 responses may occasionally have a response body, here are some examples:

{"message":"The bulk email is being processed.","bulkemailid":"621f6ce82a27ea2fea32f582"} 

This is the accompanying response for successful API requests sent to the bulk-email endpoint. Each bulk email request will have a unique bulk_email_id.

{"message":"There are some warnings for your request.","warnings": [{"type":"ALLSUPPRESSED","message":"All of the recipients provided have been suppressed.","recipients":[{"email":"hello@example.com","name":null,"reasons":["hardbounced"]}]}]}

If all or some of the recipients in the email list have been suppressed, a variation of this message will be sent back in response. There will always be a 202 response, but the email won’t be sent if all recipients are suppressed.

204 - Success

This response code is most commonly seen in response to DELETE requests sent to our recipients and webhooks endpoints.

And similar to the 200 and 201 responses, this means there were no issues found with the request and the requested action has been taken.

400 - Bad request

Bad request errors normally indicate a server-side problem. If you are still faced with this error after trying again, contact the technical support team.

401 - Unauthorized

This response will nearly always be accompanied by the following response body message:

{"message":"Unauthenticated."}

This normally suggests an issue with the token you have provided. To troubleshoot, check the following:

• Your token has been added correctly to the request

• The token has not been deleted or paused

If everything is in order, try creating a new token and attempt the request again to see if this resolves the issue.

403 - Forbidden

403 indicates an issue with the request or the account attached to the request. Several different messages can appear on a 403 response.

“Your account is suspended": If you attempt to send a request with a suspended account, you will receive this response and the request will not be fulfilled.

"Invalid scope(s) provided": This could indicate that you are using a custom API token that doesn't have the required permissions.

For example, if you’re sending 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 that has the required access.

"This action is unauthorized": This message will be returned if a rejected account tries to send a request to the email endpoint.

"You do not have permission to add another domain”: Multiple domains is a premium feature. Free and no plan accounts will see this message if they try and add an additional domain via API.

"This account access is blocked. Contact support”: This error message is returned if API/SMTP access has been switched off for your account.

"You've reached the webhook limit. Upgrade to add more webhooks”: Free and no plan accounts can add 1 webhook. If a free/no plan account holder attempts to add more than 1 webhook, they will receive this message.

404 - Not found

This is a standard 404 message. It means the endpoint URL you are attempting to send a request to cannot be found.

Check the URL and the URL formatting. If the URL is correct, contact support.

405 - Method not allowed

In the unlikely event that you receive this response code, please contact support.

408 - Request timeout

Like the 400 bad request response, request timeout errors normally indicate a server-side problem. If you continue to receive this response, please contact support.

422 - Unprocessable entity - validation error

422 usually means the API call has not been correctly formatted and/or there is a validation error due to the reasons outlined below.

"The attachments.0.content size exceeds the threshold of 10 MB.”

As stated, this will be sent in response if an attachment is included and its size exceeds the 10MB threshold.

"The to field is required.” / "The from.email field is required.” / "The subject field is required.” 

These messages can appear in response to a POST request sent to the email endpoint with the required parameters missing.

It is also not uncommon to see this message when these parameters have been added. This may indicate they have been added incorrectly or there is a problem with the formatting of the code.

"You must provide one of html, text or template_id.”

At least one of the following must be added to a send an email request for it to be successful: html version, text version, or template_id. If none of these are added to the request then this message will be returned.

As with the similar message above, it is not uncommon to see this message when these parameters have been added, which may indicate they have been added incorrectly or there is a problem with the formatting of the code.

“{recipient email} is being duplicated in the to recipients list.”

If the to.*.email is duplicated in a send an email request, this message will be returned.

"The from.email must be verified.”

The domain on the from.email must be verified on your account to be able to send emails. Please make sure this domain has a "is_verified" value set to 'true' via the API or the app. You can also add the from email address as a sender identity if you're on a Premium plan.

"This file type is not supported.”

Supported file types are listed here.

"Email quota reached.”

This response is given when an account's quota has been reached.

"Recipient limit exceeded.” / "CC recipient limit exceeded.” / "BCC recipient limit exceeded.”

This response is sent if the limit of CC and BCC recipients in a single email object is reached. The limits are as follows:

Approved accounts: Up to 10 BCC recipients and up to 10 CC recipients per email object.

Not yet approved accounts: Up to 1 BCC recipient and up to 1 CC recipient per email object.

"Could not validate the attached file. Filename and attached file does not match."

This error could mean the file name you have entered does not match. For example, if you have uploaded a GIF file but entered the file name as "me.png".

429 - Exceeded limit

"Daily API quota limit was reached.” 

Every request is counted against the quota and is reset daily at midnight UTC:

Accounts with no plan have a limit of 100 API requests per day. Free plan accounts are limited to 1000 requests per day. Premium plans can send up to 100,000 requests per day, and Enterprise 100,000+.

"Too Many Attempts.” 

This response will be sent back if you attempt to send requests to our API more frequently than we allow:

MailerSend has a default rate limit of 60 requests per minute on general API endpoints and 120 for email endpoints. Please wait for the amount of seconds indicated by 'retry-after' and try again.

500 - Server error

A 500 response indicates a server-side error. If you continue to receive this error, please contact support.