Only show these results:

Using the Email API

Get familiar with the Nylas Emails 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
  • 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": "you@your_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.

Learn More

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": "you@your_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****' \

Learn More

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

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'

Learn More

Other endpoints that support DELETE include folders and files

What's Next?

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