Nylas Email API Quickstart Guide

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.

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 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.

Other Features of the Nylas Email API

The Nylas Communications Platform provides other functionality that makes it easy for you to build your email integration.
Search functionality that is proxied to the account's provider for full-text search. Results are matched with objects that have been synced, and are then returned.
Filtering allow you to narrow requests based on specific parameters like subject line, senders and recipients, thread ids, and unread and starred status. Filters help you reduce the size of your API requests, resulting in faster performance.
Pagination makes it possible to control the number of results that are returned.
Webhooks allow your application to receive notifications when certain events occur such as emails being received or sent, or other changes to an email inbox.
Deltas enable you to process new data quickly without fetching an index of the user's email inbox or performing a large number of API calls.
Views allow you to customize the response for any endpoint to return only specific information that you want.

Quickstart Examples

This section contains examples that demonstrate basic functionality of the Nylas Email API. Some of these examples include examples of a JSON response so you can see what they return, but if you would like to try these examples yourself, complete the developer API keys guide before proceeding.

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,
• send 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://{access_token}:@api.nylas.com/messages?limit=5

[
    {
        "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
    }
]

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

for message in nylas.messages.where(limit=5):
    print(message)

const Nylas = require('nylas');

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
  
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.messages.list({limit: 5}).then(messages =>{
    for (let message of messages) {
        console.log(message);
    }
});

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.

The following example demonstrates how to return threads.

curl -X GET https://{access_token}:@api.nylas.com/threads?limit=5&view=expanded

[
    {
        "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
    }
]

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

for thread in nylas.threads.where(view='expanded', limit=5):
    print(thread)

const Nylas = require('nylas');

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
  
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.threads.list({view: 'expanded', limit: 5}).then(threads =>{
    for (let thread of threads) {
        console.log(thread);
    }
});

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://{access_token}:@api.nylas.com/messages/search?q=hello

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

for message in nylas.messages.search("hello"):
  print(message)

const Nylas = require('nylas');

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
  
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.messages.search('hello').then(messages => console.log(messages));

curl -X GET https://{access_token}:@api.nylas.com/threads/search?q=hello

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

for thread in nylas.threads.search("hello"):
  print(thread)

const Nylas = require('nylas');

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
  
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.threads.search('hello').then(threads => console.log(threads));

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 (e.g., not landing in Gmail's promotions tab), 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.

❗️

You're about to send a real email!

The following command will send an email from the account you've connected to the Nylas API to any email addresses that are specified in to, cc, and bcc. Make sure you actually want to send this email before you run this command!

curl -X POST https://{access_token}:@api.nylas.com/send \
  -d '{
    "subject": "With Love, From Nylas!",
    "body": "This email was generated using the Nylas Email API. Visit https://nylas.com for more details.",
    "to": [
        {
            "name": "My Nylas Friend",
            "email": "[email protected]"
        }
    ]
}'

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

draft = nylas.drafts.create()
draft.subject = "With Love, from Nylas"
draft.body = "This email was sent using the Nylas Email API. Visit https://nylas.com for details."
draft.to = [{'name': 'My Nylas Friend', 'email': '[email protected]'}]

draft.send()

const Nylas = require('nylas');

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
  
const nylas = Nylas.with(ACCESS_TOKEN);

const draft = nylas.drafts.build({
    subject: 'With Love, from Nylas',
    to: [{ name: 'My Nylas Friend', email: '[email protected]' }],
    body: 'This email was sent using the Nylas email API. Visit https://nylas.com for details.'
});

draft.send().then(message => {
    console.log(`${message.id} was sent`);
});

Congrats! You've sent your first email with the Nylas communication platform. Now, let's take a look at how to modify other inbox content like labels, folders, and files.

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.

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.

curl -X GET https://{access_key}:@api.nylas.com/account

{
    "id": "qmlclekd5d3bgscbhhkf",
    "account_id": "j2zpf8cju20cmzj64uj6",
    "object": "account",
    "name": "Nylas",
    "email_address": "[email protected]",
    "provider": "gmail",
    "organization_unit": "label",
    "sync_state": "running",
    "linked_at": 1470231381,
}

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

if nylas.account.organization_unit == 'label':
  print('This account uses labels!')
  
if nylas.account.organization_unit == 'folder':
  print('This account uses folders!')

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.account.get().then(account => {
    if (account.organizationUnit == 'label') {
      console.log('This account uses labels!')
    }
    if (account.organizationUnit == 'folder') {
      console.log('This account uses folders!')
    }
  });

The remainder of this section will use the labels endpoint for all examples, but folder functionality is very similar. The primary difference being that a message can have multiple labels, but be contained only in a single folder.

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://{access_key}:@api.nylas.com/labels

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

print(nylas.labels.all())

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.labels.list({}).then(labels => {
  for (let label of labels) {
    console.log(label);
  }
});

To create a label, send a POST request to the labels endpoint.

curl -X POST https://{access_token}:@api.nylas.com/labels \
  -d '{
    "display_name": "Ny New Label"
}'

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

label = nylas.labels.create()
label.display_name = "My Custom label"
label.save()

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

const label = nylas.labels.build({ displayName: 'My New Label' });
label.save();

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://{access_token}:@api.nylas.com/messages/{message_id} \
  -d '{
    "label_ids": "{label_id}"
}'

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)
message = nylas.messages.get('{id}')
message.add_label('{label_id}')
message.save()

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.messages.find('{id}').then(message => {
  const existingLabel = nylas.labels.find('{labelId}');
  message.labels.push(existingLabel);
  });
  message.save();
})

Finally, to delete a label, make a DELETE request to the labels/{id} endpoint.

curl -X DELETE https://{access_token}:@api.nylas.com/labels/{id}

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

nylas.labels.delete('{id}')

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.labels.delete("{id}")

Other endpoints that support DELETE include folders and files

Next Steps

How Nylas Works - Take a look at the Nylas architecture to see how we sync billions of emails.

Quickstart Guides - Get up to speed quickly with our SDKs using our quickstart guides for Python and Node.js, or explore the Nylas Calendar or Contacts API.

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.

Integration Guides - Ready to start building your integration? Our integration guides cover what it takes to incorporate email functionality into your app. They cover best practices for using the Nylas Communications Platform and provider-specific advice for Google, Microsoft, and more.

Set up Postman - Postman makes it easy to explore the Nylas Email API.

API Reference - Our API reference provides all the detail you need to know to use the Nylas Communications Platform.