Version:
Only show these results:

v2 Nylas Email API overview

The Nylas Email API gives you a secure and reliable connection to your end users' inboxes. This enables you to sync both historic and live email data, and perform bi-directional sync with full CRUD (Create, Read, Update, Delete) capabilities for most providers. The API provides a REST interface that allows you to do the following tasks:

  • Read data from email messages and threads, such as message content, sender and recipient information, and more.
  • Organize email inboxes using labels and folders.
  • Update the unread and starred status of email messages.
  • Create drafts and send email messages.
  • Search inboxes for specific content.
  • Manage and download attachment files.

How the Email API works

When you send an email message using the Email API, it is not sent from the Nylas servers. Instead, when you make the API call, Nylas connects to the provider's email SMTP server using the end user's credentials, and uploads the email message. One of three things then happens:

  • The email is accepted for delivery. Nylas returns a 200 response to your application.
  • The email is rejected by the provider. Nylas passes the rejection code and error message to your application.
  • The email is delayed. This might happen if the email server is busy, or if the email message contains a large attachment. Nylas recommends waiting three minutes for the request to time out before making any new API calls.

How Nylas syncs email messages

When an end user authenticates with your Nylas application, the Nylas sync engine starts pulling all of the data it has access to for their account.

Nylas prioritizes the most recent email messages, but messages aren't always added in reverse-chronological order. As new email messages arrive in the end user's inbox, Nylas syncs them in parallel with historical sync jobs. Nylas also caches files (attachments) and copies of the raw RFC-2822 MIM message in an Amazon S3 bucket for seven days.

For more information about Nylas' sync process, see the Platform documentation.

One-click unsubscribe requirements for Google messages

As of February 2024, Google requires that users who send more than 5,000 email messages per day to Gmail email addresses include one-click unsubscribe headers in each of their marketing and subscribed emails (see Google’s official Email sender guidelines). This is along with the visible unsubscribe links that must be in the body content of all marketing and subscribed email messages.

To set up one-click unsubscribe headers, include the custom_headers object in your Send Message request. This object accepts a set of key-value pairs, each of which represents the header’s name and its value. You must include the following headers:

  • List-Unsubscribe-Post: List-Unsubscribe=One-Click
  • List-Unsubscribe: The unsubscribe link (for example, a mailto link that uses the end user’s email address, or a link to your list management software).
"custom_headers":[
  {
    "name": "List-Unsubscribe-Post",
    "value": "List-Unsubscribe=One-Click"
  },   
  {
    "name": "List-Unsubscribe",
    "value": "<mailto: nyla@example.com?subject=unsubscribe>,  <https://mailinglist.example.com/unsubscribe.html>"
  }
]

Email API endpoints

The following sections describe the endpoints that the Nylas Email API provides. For more information, see the Email reference documentation.

Messages and Threads endpoints

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 the message was sent, the sender's email address, to whom it was sent, and the message body. They can also contain files (attachments), calendar event invitations, and more. For more information, see the Messages reference documentation.

Threads are first-class objects that represent collections of messages that are related to one another. Threads result from people replying to an email conversation. For Gmail and Microsoft Exchange accounts, Nylas threads messages together so that they're as similar as possible to their representation in the provider's environment. For all other providers, including generic IMAP, Nylas threads messages using a custom JWZ-inspired algorithm. For more information, see the Threads reference documentation.

📝 Note: Threaded email messages that you forward to other participants remain in the thread on both the provider and Nylas.

Deleting email messages

Nylas does not directly delete email messages on the provider. Instead, Nylas moves the message to the end user's Trash folder or adds the Trash label to the message. The provider usually "empties" the Trash (deletes all email messages in the folder or with the label) after a configured period of time. This allows the end user to restore the email message by either moving it out of the Trash folder or removing the label, and prevents scripts from mass-deleting messages.

Folders and Labels endpoints

Folders are the primary component for organizing email inboxes on most providers. They also behave like regular IMAP or filesystem folders. An email message can be contained within one folder only, but a thread with many email messages might span multiple folders.

Instead of folders, Gmail uses labels to organize email inboxes. An email message can be associated with multiple labels.

For more information, see the Nylas API reference documentation:

Label limitations

You should keep the following limitations in mind when you work with labels:

  • You can add only one of the All Mail, Trash, or Spam labels to an email message.
  • When you add either the Trash or Spam label to an email message, the Inbox label is removed.
  • When you add the Inbox label to an email message, the Trash and Spam labels are removed, and the All Mail label is added (if necessary).

Files and Attachments endpoints

Nylas considers any data attached to an email message to be a file. The Nylas Email API allows you to download existing attachments from messages and threads, and upload files to be sent. For more information, see the v2 Files reference documentation.

Drafts endpoints

A draft is a special kind of email message that hasn't been sent. Because of this, the body contents and recipients are mutable while the draft remains unsent. For more information, see the Drafts reference documentation.

Email delivery services

An email delivery service sends email messages on behalf of other domains. Nylas is not an email delivery service, and does not manage the following settings and processes: