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 NylasThe 5 Biggest Email API Pitfalls
Email APIs are full of difficult, unexpected pitfalls. Learn how Nylas makes it easy for developers to build their email integration.
Email APIs are full of difficult, unexpected pitfalls. Learn how Nylas makes it easy for developers to build their email integration.
Incorporating email functionality into your app can seem quite simple on the surface, but the reality is that the email API ecosystem can be fraught with pitfalls and complexities. Maybe you want to implement functionality like sending an email, or displaying email conversations from a user’s inbox. Most email providers have an API, so it should be easy to build these capabilities yourself, right?
Not so fast! Once you start digging into the details of your integration, you’re likely to find out that many email APIs are missing crucial capabilities that drastically increase the amount of effort you’ll need to put into your integration. Not to mention, every email API has its own conventions for how to handle common tasks, and these conventions are typically optimized for the needs of the email provider rather than developers who are trying to implement communications functionality into their app.
This blog post will cover the 5 biggest pitfalls you’re likely to encounter when integrating an email API into your app, and how Nylas is the clear solution for developers who want to build the best email integration.
Most email service providers, like Gmail, Exchange, Office 365, and Outlook, have their own APIs that each have unique characteristics. The more providers you want to work with, the more technologies, protocols, and frameworks you’ll need to incorporate into your stack. The next table provides a sample of the technologies some of the major email providers use.
| Gmail | EWS | Microsoft Graph | IMAP/SMTP | |
|---|---|---|---|---|
| Communication Protocol | REST | SOAP | REST | HTTP |
| Data Type | JSON | XML | JSON | MIME |
| Authentication | OAuth – Refresh Tokens | OAuth | OAuth | Varies |
| Notifications | Webhooks | Webhooks | Temporary Webhooks, Deltas | None |
The complexity of the email API ecosystem is what led to the creation of the Nylas Email API, which provides a single point of integration that automatically connects your app to 100% of email providers. With Nylas, you don’t need to worry about incorporating multiple authentication services, data types, and notification systems. Instead, you build one integration with Nylas and we abstract away all of these differences.
Sending an email is one of the most integral, yet basic components of an email integration. Conceptually, it’s extremely simple, but practically speaking it involves an extensive process for some email providers.
For example, the Gmail API requires you to create raw MIME text that complies with RFC 2822 when creating new drafts. As a result, you need to provide proper email headers, body content, date and time information, originator details, and all other data that’s required to send an email. Any misconfiguration at this stage can result in poor deliverability and even cause your emails to land in the receiver’s spam folder. This is only for Gmail, if you want to integrate with providers like Exchange, Outlook, and Office 365, you’ll need to contend with their unique characteristics when sending emails as well.
Additionally, there are a number of ways that sending an email via an email API can fail because of things outside your control. Most email providers have rate limits for user and API interactions that you’ll encounter if you have users that regularly send large numbers of emails. It’s also fairly common to see server errors that need a solution like an exponential backoff retry pattern.
The Nylas Outbox endpoint beta lets you send emails with a very simple JSON representation. It will automatically handle the most common email send errors for you and is the simplest way to send an email via an Email API:
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": "email@example.com",
"name": "My Friend"
}]
}'
It can be easy to think about email as being similar to physical mail, with independent messages that are delivered as self-contained packages. But, in reality, a single email is often part of a larger conversation, and the other emails in those conversations play an important role to help users understand the greater context. If you want to integrate content from your user’s email inboxes into your app, you need to take this context into consideration and build proper groupings of emails that provide your users with a more cohesive, natural view of their email inbox.
Some email APIs treat threads as second-class objects, which means you’ll need to make separate requests for each message that is part of a conversation. These requests can add up if you’re working with numerous email threads that all contain more than one message.
The Nylas Threads endpoint makes it extremely easy to extract data from all email messages that are a part of a thread with a single request that includes an optional parameter to view the expanded contents of the thread:
curl -X GET 'https://api.nylas.com/threads/{thread_id}?view=expanded' \
-H 'Authorization: Bearer ACCESS_TOKEN'
{
"object": "thread",
"subject": "Take a look at our new line of nuclear engines.",
"messages": [
{
"object": "message",
"subject": "Take a look at our new line of nuclear engines.",
"body": "<div dir=\"ltr\">We've released our latest line of nuclear engines, take a look at the attached product catalog.<br clear=\"all\"><div><br></div>-- <br><div dir=\"ltr\" class=\"gmail_signature\" data-smartmail=\"gmail_signature\"><div dir=\"ltr\"><div><div dir=\"ltr\"><div><div><font size=\"4\" face=\"trebuchet ms,sans-serif\">Albert</font><font size=\"4\"> Einstein</font><br></div></div>Particle Tech Inc.<br></div></div></div></div></div>",
"date": 1610400855,
"files": [ "7dh29ka03" ],
"from": [
{ "email": "al@particletech.com", "name": "Albert Einstein" }
],
"to": [
{ "email": "marie@radioactivity.com", "name": "Marie Curie" }
],
}
],
"first_message_timestamp": 1610400855,
"has_attachments": true,
"last_message_timestamp": 1611244437,
}
The Nylas Email API represents email messages in a simple JSON format with all the data you’d expect like the subject, body, participants, and more, but not all email APIs are this simple. For example, the Gmail API provides the body as a base64url encoded MIME string, and EWS, Exchange, and Office 365 each have their own unique ways of representing an email body content.
Furthermore, extracting the email body is only half the battle. Email messages typically contain large amounts of superfluous information, even if the people involved only typed a few sentences into their email client at each step of the conversation. An email body might contain HTML, copied content from previous emails in the chain, images, and signatures. You need to filter this information out if you want to focus on the conversation at hand.
The Nylas Neural API includes the Conversation endpoint that enables developers to extract the Clean Conversation from an email message with a single API request:
curl -X PUT 'https://api.nylas.com/neural/conversation' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"message_id":"{message_id}"
}'
You can also extract email signatures with the Nylas Signature endpoint:
curl --request PUT 'https://api.nylas.com/neural/signature' \
-h 'Authorization: Bearer {access_token}' \
-d '{
"message_id": ["{message_id}"],
"parse_contacts": true
}'
When you run these two API requests, the existing email message object will be altered to include new values for the conversation and signature fields. The former contains only the conversation text, and the latter contains the sender’s signature:
[
{
"object": "message",
"subject": "Take a look at our new line of nuclear engines.",
"conversation": "We've released our latest line of nuclear engines, take a look at the attached product catalog.",
"from": [
{
"email": "albert.einstein@physics.com",
"name": "Albert Einstein"
}
],
"contacts": {
"job_titles": [
"Director of Engineering"
],
"phone_numbers": [
"123-456-8901"
],
"emails":["al.einstein@physics.com"],
"names":[
{
"first_name":"Albert",
"last_name": "Einstein"
}
],
}
"signature": "Albert Einstein\n\nDirector of Engineering\n\nPhone: +1.234.567.8901\n\nSkype: AlbertEinstein \n\nParticle Technologies"
}
]
File attachment management varies greatly between email APIs. The Gmail API has three separate functions to upload files for email attachments depending on the type of file. Other APIs like EWS require you to convert files to a base64url encoded string before uploading them. You’ll need to account for all of these differences if you need to process file attachments from email inboxes.
The Nylas Files endpoint makes it extremely easy to upload, download, and manage email file attachments. You can upload a new file with a single API request:
curl -X POST 'https://api.nylas.com/files/' \
-H 'Authorization: Bearer {access_token}' \
--form 'file=@/path/to/file'
Once a file is uploaded, you can attach it to any future emails that you send by including the file ID in the request:
curl -X POST 'https://api.nylas.com/outbox' \
-h 'Authorization: Bearer <access_token>' \
-d '{
"subject": "Welcome to Nylas!",
"body": "This email was sent using the Nylas email API. Visit https://www.nylas.com for details."
"file_ids": [ "734hhdafs46jgfd"],
"to": [
{
"email": "dorothy@spacetech.com",
"name": "Dorothy"
}
]
}'
Nylas builds our products with the goal of enabling developers to build better products. We’re the experts at email integrations so you don’t have to be, and we’ve designed our Email API to make it much easier to navigate the pitfalls developers face when building communications functionality. The benefits of Nylas don’t stop with the features outlined in this article, we also protect our customers from third-party API downtime, and we’re here to help when you need to go through third-party security reviews. If you’re ready to start building with Nylas, sign up for a free trial today.
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.
