Only show these results:

Using the Email API

In this guide, we'll go over how to use the Nylas Email API.

You'll learn how to:

  • Read content from an email inbox including messages, threads, folders, labels, and drafts.
  • Search for email messages and threads.
  • Send emails.
  • Update email labels, file attachments, unread status, stars, and folders, and more.
  • 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 several pieces of information, such as a timestamp of the message, the sender's address, the recipient, and the message body. They can also contain file attachments, calendar invites, and more.

The example below demonstrates how to return the five 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": "you@your_company.com",
"name": "Your Company"
}
],
"unread": true
}
]

By default, the messages endpoint provides the 100 most recent messages, but this example limits results to five messages. Check out our documentation on pagination to learn 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's 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.

The example below demonstrates how to return the five most recent threads for an account.

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": "you@your_company.com",
"name": "Your Company"
}
],
"snippet": "Use Nylas for your email integration!",
"starred": false,
"subject": "Welcome to Nylas!",
"unread": false,
"version": 1
}
]

Similar to the messages example, this example is limiting the number of responses to five. 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're 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. Examples of searching for messages and threads are below:

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, check out our documentation on the search reference.

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 rate-limiting and abuse detection from the back-end provider. Read our best practices for improving deliverability to make sure your messages are sent out.

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 --request POST \
--url https://api.nylas.com/send \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"subject": "From Nylas",
"to": [
{
"email": "[email protected]",
"name": "Nylas"
}
],
"cc": [
{
"name": "Dorothy Vaughan",
"email": "[email protected]"
}
],
"bcc": [
{
"name": "Hedy Lamarr",
"email": "[email protected]"
}
],
"from": [
{
"name": "Your Name",
"email": "[email protected]"
}
],
"reply_to": [
{
"name": "Nylas",
"email": "[email protected]"
}
],
"reply_to_message_id": "<MESSAGE_ID>",
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"file_ids": [
"<FILE_ID>",
"<FILE_ID>"
]
}'
{
"account_id": "{account_id}",
"bcc": [
{
"email": "Albert Einstein",
"name": "[email protected]"
}
],
"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": [
{
"email": "George Washington Carver",
"name": "[email protected]"
}
],
"date": 1557950729,
"events": [
{}
],
"files": [
{
"content_disposition": "attachment",
"content_type": "image/jpeg",
"filename": "image.jpeg",
"id": "{image_id}",
"size": 2648890
}
],
"folder": {
"display_name": "string",
"id": "string",
"name": "string"
},
"from": [
{
"name": "Marie Curie",
"email": "[email protected]"
}
],
"id": "string",
"object": "message",
"reply_to": [
{
"email": "[email protected]",
"name": "Stephanie Kwolek"
}
],
"snippet": "string",
"starred": true,
"subject": "string",
"thread_id": "string",
"to": [
{
"email": "[email protected]",
"name": "Dorothy Vaughan"
}
],
"unread": true,
"labels": [
{
"display_name": "Important",
"id": "{label_id}",
"name": "important"
}
]
}

Create and Modify Inbox Content

Most endpoints on the Nylas Email API offer the ability to modify objects with PUT and POST. The modifications that can be made are:

  • Threads and Messages - You can modify labels, unread status, stars, and move them to new folders.
  • Folders and Labels - You can change the names.
  • Files - You can 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 are contained only in a single folder. In general, Gmail uses labels, while 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 will either be folder or label.

The examples below use 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'll need the id of both the message you want to modify and the label you want to add. 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. An example is shown below:

curl -X PUT 'https://api.nylas.com/messages/{message_id}' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"label_ids": ["{label_id}", "{label_id}"]
}'

To delete a label, make a DELETE request to the labels/{id} endpoint. An example is shown below:

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?

  • Tutorials - Check out our tutorials to learn how to carry out common functionality such as sending emails, reading data from an email inbox, accessing file attachments, and organizing inboxes with labels and folders.
  • API Documentation - Our API documentation provides all the information you need to use the Nylas Communications Platform.
  • How Nylas Works - Take a look at the Nylas architecture to see how we sync billions of emails.