Calendar management
Embedded contextual email
Scheduling automation
Automated outreach
Telehealth
Marketplaces
Recruiting
Document management
Real estate
Communications software
Docs
SDKs
Tutorials
API status
Changelog
Support
Blog
Events
Guides
Newsroom
Partners
Build vs. buy
Customer stories
Trust & security
Why NylasHow Nylas Outbox Automatically Handles Email API Send Errors
Learn how the Nylas Platform automatically handles email API send errors, allowing developers to build email integrations much quicker.
Learn how the Nylas Platform automatically handles email API send errors, allowing developers to build email integrations much quicker.
Nylas has expanded our Email API with the launch of our Outbox endpoint beta that makes it much easier for developers to send emails from their user’s email inbox. It’s the next big step for Nylas on our journey to build lean-code solutions for communications and scheduling integrations. Perhaps the most underrated feature is the new automatic error handling Nylas provides when sending emails. It represents a significant quality-of-life improvement for developers who build with Nylas.
If you want to build an integration with external APIs, you need to anticipate all of the ways requests to that integration can go wrong. Even a simple task like sending an email can fail in various ways, some of which are very specific to the job and the email provider. To complicate things further, every email provider has unique usage limitations, restrictions, and associated errors.
Wouldn’t it be great if those could be abstracted away, enabling you to focus more on user functionality than back-end API error handling? This abstraction is precisely what the Nylas Outbox endpoint handles for you. For example, if you make a POST request to the Outbox endpoint to send an email:
curl -X POST 'https://api.nylas.com/outbox' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"send_at": 1008720000,
"subject": "One Email API to rule them all",
"body": "Keep it secret, keep it safe... or share it with your friends.",
"to": [{
"email": "frodo@baggins.com",
"name": "Frodo Baggins"
}]
}'
Nylas will make sure the email gets sent, even if we encounter common third-party API errors. What does this mean exactly? Let’s take a deeper dive into the errors that APIs for email providers like Gmail, Exchange, Outlook, and Office 365 commonly return when sending emails and how the Nylas Outbox endpoint abstracts this complexity away.
Most Email providers have some form of built-in user rate limiting designed to reduce server load, and HTTP 429 errors are among the most commonly-encountered errors you’ll need to handle when sending emails. Each provider has its own rules for rate limiting and recommendations for how developers should handle them. For example, the Gmail API has three situations that can trigger an HTTP 429 error:
For the first two scenarios, the general recommendation is to use an exponential backoff process to retry the requests. Alternatively, sometimes the API will return a time to retry value that indicates a specific time in the future when you can retry the request.
The third scenario might not be something that’s under your control. You could see better results by limiting the number of API requests your app makes at once. Still, if the user has many apps and services that integrate with their email account, you’ll need to initiate a retry process to find times that traffic for the user account is low.
These scenarios can sometimes be resolved via request batching: grouping multiple requests together into a single request to reduce the total number of API interactions. However, batching isn’t always an option for every use case, so it’s something that developers need to take a closer look at to understand if it fits their needs.
One crucial thing to keep in mind is that the Gmail API doesn’t immediately start reporting 429 errors when a user hits their bandwidth or email sending limits; API requests to send an email that return a successful 200 status code during this time might not actually get sent. This delay can take several minutes, so you will need custom logic to ensure that the emails you intended to send got sent.
Microsoft has similar rate limits for their email APIs for Exchange, Outlook, and Office 365; their general advice matches Gmail’s. With that said, self-hosted versions of Exchange have several configuration possibilities for rate limiting, meaning that rate limiting for Microsoft email accounts can vary at the individual level. You’re likely to encounter this problem if you need to support Microsoft email accounts.
Email APIs can return a handful of HTTP 5XX errors to indicate when their API service has encountered an internal issue; this group of errors includes 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout. In general, most APIs consider it acceptable to retry requests that result in one of these errors. The recommendation is to make any subsequent retries in an exponential backoff pattern.
The Gmail API uses HTTP 403 errors to indicate when a user or app has exceeded API rate-limits across all of Google’s services. The Gmail API will return HTTP 403 errors in two scenarios:
The Nylas Outbox endpoint abstracts away these difficulties by auto-detecting when a user reaches their bandwidth or concurrent request limits. We also implement an automatic retry policy for HTTP 5XX errors on your behalf too. When any of these errors occur, the Nylas Sync Engine stores the email and sends it as soon as the third-party API lifts the restrictions; we handle the entire task of managing the retry process. At any time, you can check on the status of an email sent via the Outbox endpoint by making a GET request.
curl -X GET 'https://api.nylas.com/outbox' \ -H 'Authorization: Bearer ACCESS_TOKEN'
If the email is unsent, it will have a status of pending, and will include a send_at attribute that indicates the next retry time:
[
{
"send_at": 1008720000,
"status": "pending",
"subject": "One Email API to rule them all",
"body": "Keep it secret, keep it safe... or share it with your friends.",
"id": "l0trru13z"
"to": [{
"email": "frodo@baggins.com",
"name": "Frodo Baggins"
}
]
Outbox is only one component of the lean-code solutions Nylas provides for communications integrations, and it pairs well with other features we offer like Email Categorization, Clean Conversations, and Signature Extraction. If you’re ready to build your email integration today, sign up for a free account.
Please enter your email address and receive the latest updates.
Ben is the Developer Advocate for Nylas. He is a triathlete, musician, avid gamer, and loves to seek out the best breakfast tacos in Austin, Texas.
