The Nylas Email API gives you a secure, reliable connection to your user’s inboxes that enables you to sync historic and live email data into your application in real-time and perform bi-directional email sync with full CRUD (create, read, update, delete) capabilities for Gmail, Microsoft Exchange, Outlook.com, Yahoo! Mail, AOL, IMAP, and the rest with just a few lines of code.
The Nylas Email API provides a REST interface that includes functionality to
- Read data from email messages and threads, such as email content, sender and recipient information, subject lines, dates, and more.
- Organize email inboxes with labels and folders.
- Update the unread and starred status of email messages.
- Manage and download file attachments.
- Create drafts and send emails.
- Search email inboxes for specific content.
Email API Endpoints
This section covers all of the endpoints the Nylas Email API provides to enable you to integrate full email functionality into your app.
Outbox
Outbox lets you send a message with a high rate of deliverability and schedule messages to be sent.
Messages
Messages are the fundamental object of the Nylas platform and the core building block for most email applications. They contain several pieces of information, such as when a message was sent, the sender's address, to whom it was sent, and the message body. They can also contain file attachments, calendar event invitations, and more.
Threads
Threads are multiple messages that are grouped together into a single, first-class object. Nylas threads messages together using a variety of heuristics; on Gmail and Microsoft Exchange accounts, messages are threaded together as close as possible to the representation in those environments. For all other providers (including generic IMAP), messages are threaded using a custom JWZ-inspired algorithm.
Folders
Folders are the primary component for organizing email inboxes from most providers and they behave like normal IMAP or filesystem folders. A message can only be contained within a single folder, but a thread with many messages might span multiple folders.
Labels
Gmail uses labels to organize email inboxes rather than folders, and messages may have more than one label. Nylas makes it easy to detect when accounts use this method of organization so you can ensure your end users have an experience that matches their provider of choice.
Files
Files are any data attached to messages. Nylas allows you to download existing attachments from messages and threads and upload new files to be sent.
Drafts
Drafts are a special kind of message that has not been sent, and therefore its body contents and recipients are still mutable. The drafts endpoints let you read and modify existing drafts, create new drafts, send drafts, and delete drafts.
Basic Email API Functionality
The examples in this section will cover how to use the Nylas Email API to
- Read content from an email inbox including messages, threads, folders, labels, and drafts
- Search for email messages and threads
- Rend emails.
- Update email labels, file attachments, unread status, stars, and folders, and
- Delete drafts, files, and folders.
Read Content from User Email Inboxes
There are two ways to read the emails in a user's inbox: messages and threads.
Messages
Messages are the fundamental object of the Nylas platform and the core building block for most email applications. They contain information like when the message was sent, the sender's address, the message body, attachments, and more.
The next example demonstrates how to return the 5 most recent emails for an account.
curl -X GET 'https://api.nylas.com/messages?limit=5' \
-H 'Authorization: Bearer ACCESS_TOKEN'
[
{
"account_id": "qmlclekd5d3bgscbhhkf",
"bcc": [],
"body": "<html>\n<head>\n <meta charset=\"UTF-8\">\n <style type=\"text/css\">\n html {\n -webkit-text-size-adjust:none;\n }\n body {\n width:100%;\n margin:0 auto;\n padding:0;\n}\n p {\n width:280px;\n line-height: 16px;\n letter-spacing: 0.5px;\n }\n </style>\n <title>Welcome ... </html>",
"cc": [],
"date": 1557950729,
"events": [],
"files": [],
"folder": {
"display_name": "Inbox",
"id": "kekzhtt9hmrsad98xjzj",
"name": "inbox"
},
"from": [
{
"email": "[email protected]",
"name": "My Nylas Friend"
}
],
"id": "j2zpf8cju20cmzj64uj6",
"object": "message",
"reply_to": [
{
"email": "[email protected]",
"name": "My Nylas Friend"
}
],
"snippet": "Use Nylas for your email integration!",
"starred": false,
"subject": "Welcome to Nylas",
"thread_id": "w2kh2bfjvzsgfpkb3b0t",
"to": [
{
"email": "[email protected]_company.com",
"name": "Your Company"
}
],
"unread": true
}
]
By default, the messages endpoint provides the most recent 100 messages, but this example limits results to 5 messages. Refer to the docs on pagination to learn about how to use limits and offsets to control the number of objects that are returned.
Review the Message Object in the API documentation to learn about the fields this endpoint returns.
Threads
Threads combine multiple messages from the same conversation into a single first-class object that is similar to what users expect from email clients. For providers like Gmail and Microsoft Exchange, messages are threaded to be as close a representation as possible to the respective email providers.
curl -X GET 'https://api.nylas.com/threads?limit=5' \
-H 'Authorization: Bearer ACCESS_TOKEN'
[
{
"account_id": "qmlclekd5d3bgscbhhkf",
"draft_ids": [],
"first_message_timestamp": 1557950729,
"folders": [
{
"display_name": "Inbox",
"id": "j2zpf8cju20cmzj64uj6",
"name": "inbox"
}
],
"has_attachments": false,
"id": "kekzhtt9hmrsad98xjzj",
"last_message_received_timestamp": 1557950729,
"last_message_sent_timestamp": null,
"last_message_timestamp": 1557950729,
"message_ids": [
"mf4jy5rf06d4l9upl8xb"
],
"object": "thread",
"participants": [
{
"email": "[email protected]",
"name": "My Nylas Friend"
},
{
"email": "[email protected]_company.com",
"name": "Your Company"
}
],
"snippet": "Use Nylas for your email integration!",
"starred": false,
"subject": "Welcome to Nylas!",
"unread": false,
"version": 1
}
]
Much like the messages example, this example is limiting the number of responses to 5. However, it also uses a feature of the Nylas API called views that allows you to customize the response of an endpoint. In this case, we are requesting the expanded view, which expands the threads object to include all message and draft sub-objects.
Other content that can be read from a user's inbox include folders, labels, files, and drafts.
Search an Inbox
The search sub-endpoint is used to run a full-text search on account providers. It returns 40 results by default. Search can be used on both messages and threads.
curl -X GET \
https://api.nylas.com/messages/search?q=hello \
-H 'Authorization: Basic WVVUWjZ****' \
curl -X GET \
https://api.nylas.com/threads/search?q=hello \
-H 'Authorization: Basic WVVUWjZ****' \
To learn more about query syntax for common email providers, review the search reference information in the Nylas docs.
Send an Email
It's time to send your first email using the Nylas email API!
With Nylas, all emails are sent through the account's original SMTP/ActiveSync gateway, just as if the message was sent using any other app. This means messages sent through Nylas have very high deliverability, but may also be subject to backend provider rate-limiting and abuse detection. Ensure you send messages wisely! Read our best practices for improving deliverability.
The following example demonstrates how to send an email with the Nylas API. Make sure you send it to an email address that is different than the account you are sending it from.
curl --location --request POST 'https://api.nylas.com/outbox' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"subject": "Welcome to Nylas!",
"send_at": 1608156000,
"to": [
{
"email": "[email protected]",
"name": "Dorothy"
}
],
"from": [
{
"name": "[email protected]",
"email": "Katherine"
}
],
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details."
}'
{
"account_id": "5tgncdmczat02216u7d6uypyi",
"bcc": [],
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"cc": [],
"date": "Tue, 15 Dec 2020 20:52:21 GMT",
"events": [],
"files": [],
"from": [
{
"email": "Katherine",
"name": "[email protected]"
}
],
"id": "8bup1y1szsybrj91e86l9l07o",
"job_status_id": "996mfx5bg5yzay4bpedug7of2",
"labels": [],
"object": "draft",
"outbox_info": {
"id": "bzjc8nrklhpybk71sbt3o1lve",
"message_id": "8bup1y1szsybrj91e86l9l07o",
"send_at": "Wed, 16 Dec 2020 22:00:00 GMT",
"sent_at": null
},
"reply_to": [],
"reply_to_message_id": null,
"snippet": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"starred": false,
"subject": "Sent at 4:00",
"thread_id": "abnnykhlipvgknbvubgfrqknx",
"to": [
{
"email": "[email protected]",
"name": "Dorothy"
}
],
"unread": false,
"version": 0
}
Learn more about Sending Emails.
Create and Modify Inbox Content
Most endpoints on the Nylas Email API offer the ability to modify objects with PUT and POST.
- Threads and Messages - Modify labels, unread status, stars, and move to new folders.
- Folders and Labels - Change names
- Files - Upload files to use as attachments.
Create and Modify Folders and Labels
Folders and labels are a fundamental component of organizing and managing email inboxes. All accounts that have been authenticated to the Nylas communication platform provide access to only one of these two objects, but they behave in a similar manner.
The difference between folders and labels is that messages can have multiple labels, but be contained only in a single folder. In general, Gmail uses labels, and all other providers use folders.
To find out whether an account support folders or labels, make a GET request to the account endpoint and check the value for organization_unit, it should either be folder or label.
The following examples uses labels.
curl -X GET \
https://api.nylas.com/account \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
{
"id": "awa6ltos76vz5hvphkp8k17nt",
"account_id": "awa6ltos76vz5hvphkp8k17nt",
"object": "account",
"name": "Ben Bitdiddle",
"email_address": "[email protected]",
"provider": "gmail",
"organization_unit": "label",
"sync_state": "running",
"linked_at": 1470231381,
}
To view all labels the account has configured, make a GET request to the labels endpoint. This will return, among other objects, an id that can be used to modify the labels and attach them to messages and threads.
curl -X GET 'https://api.nylas.com/labels' \
-H 'Authorization: Bearer ACCESS_TOKEN'
To create a label, send a POST request to the labels endpoint.
# Create a new folder
curl -X POST 'https://api.nylas.com/folders' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"display_name": "My New Folder"
}'
To add a label to a message, you will first need the id of both the message you want to modify and the label you want to apply. Use the relevant commands found earlier in this guide to get these values. Then, make a PUT request to the messages/{id} endpoint. This will overwrite any labels that are currently applied.
curl -X PUT 'https://api.nylas.com/messages/{message_id}' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"label_ids": ["{label_id}", "{label_id}"]
}'
Finally, to delete a label, make a DELETE request to the labels/{id} endpoint.
curl -X DELETE 'https://api.nylas.com/labels/{id}' \
-H 'Authorization: Bearer ACCESS_TOKEN'
Other endpoints that support DELETE include folders and files
What's Next?
- Learn how to send emails using Outbox Endpoint Guide
- Tutorials - Check out our plethora of tutorials to learn how to carry out common functionality, like sending emails, reading data from an email inbox, accessing file attachments, and organizing inboxes with labels and folders.
- API Reference - Our API reference provides all the detail you need to know to use the Nylas Communications Platform.
- How Nylas Works - Take a look at the Nylas architecture to see how we sync billions of emails.
Updated about a month ago