Sometimes, delivery of email messages might fail if the end user’s email gateway rejects the message. This can happen for a number of reasons, including illegal attachment data, bad credentials, or rate-limiting.
If the email message is submitted successfully, the server responds with a 200 OK HTTP response. If the message is not submitted, the server responds with an error code.
If any participant email addresses contain non-ASCII characters (for example, characters with accents or other diacritics), email message delivery fails. When this happens, Nylas returns a 402 error with the following message: “Sending to at least one recipient failed.”
Nylas error codes
The following table describes the error codes you might encounter when sending email messages with Nylas.
| Status code | Type | Description |
|---|---|---|
400 | Bad request | Your request was not formed properly, or contains an invalid parameter. The most common cause is invalid JSON. |
402 | Message rejected | The provider rejected the email message because of its content or recipients. If the error includes “Sending to at least one recipient failed”, it means that your email message might have been delivered to only a subset of recipients. |
403 | Unauthorized | The server was not able to authenticate with the provider. Re-authenticate the end user and try again. |
422 | Mail provider error | An error occurred while the provider was sending the email message. See the server_error parameter in the response JSON for more information. |
429 | Quota exceeded | The end user has exceeded their provider’s sending quota. There is no reliable way to determine these limits. Wait and try again later. |
429 | Account throttled | The account is in a throttled state and the mail server has asked Nylas to temporarily stop making requests. Wait and try again later. |
429 | Nylas API rate limit | You made too many requests to the Nylas API too quickly. Wait and try again later. For more information, see the Rate limiting documentation. |
503 | Service unavailable | Nylas encountered an error while connected to the provider. Wait and try again later. |
For more information about errors and status codes, see Nylas API responses, errors, and HTTP status codes.
Nylas error responses
When you receive an error from Nylas, it includes a JSON payload with information about the specific error.
| Parameter | Type | Description |
|---|---|---|
type | string | The type of error encountered. |
message | string | A brief, human-readable description of the error. |
server_error | string | (Optional) The original error returned by the end user’s email server. |
Microsoft sending errors
Sometimes, you might receive a 120 error from Microsoft when attempting to send an email message, similar to the following example:
120 MailSubmissionFailed The server failed to submit the message for delivery.
This is usually because you’re trying to send an email message using an email address other than the one you authenticated to Nylas (for example, if you authenticated using [email protected], but you try to send an email message from [email protected]). When this happens, Nylas returns a 422 error with the following message: “Message delivery submission failed.” It might also return a 429 error.
Follow these steps to troubleshoot the error:
- Check the email account you’re trying to send the email message with, and verify that it’s the same as the account you authenticated to Nylas.
- Try to send the email message again with exponential backoff.
- Confirm that the Exchange server hasn’t quarantined Nylas’ dummy devices. See Checking for quarantined EAS devices.
- Confirm that your Microsoft 365 settings match Nylas’ recommended settings.
If these troubleshooting steps don’t fix the error, you might be encountering a more complex issue that occurs on a small number of hosted Exchange and Microsoft 365 servers. For further troubleshooting, contact your email administrator or provider.