Email API Overview
The Nylas Email API gives you a secure and reliable connection to your user’s inboxes. This enables you to sync both historic and live email data into your application in real-time, as well as perform bi-directional email sync with full CRUD (Create, Read, Update, Delete) for most email providers.
The Nylas Email API provides a REST interface that includes the functionality to do the following:
- 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.
- Create drafts and send emails.
- Search email inboxes for specific content.
- Manage and download file attachments.
Email API Endpoints
This section covers the endpoints that the Nylas Email API provides to enable you to integrate full email functionality into your app.
Messages and threads
Messages are the fundamental object of the Nylas platform and the core building block for most email applications. Messages contain several pieces of information, such as when the message was sent, the sender's address, to whom it was sent, and the message body. They can also contain files (attachments), calendar event invitations, and more.
Threads are first-class objects that represent a collection of messages. Messages are threaded together with a variety of heuristics. For Gmail and Microsoft Exchange accounts, messages are threaded together in a way that is as close as possible to the representation in their environments. For all other providers, including generic IMAP, messages are threaded using a custom JWZ-inspired algorithm.
Forwarded Emails
Emails that are forwarded to other people in a thread remain in the thread both on the provider and Nylas.
Folders
Folders are the primary component for organizing email inboxes from most providers. They also behave like regular 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.
Label Rules
When adding and removing certain Gmail labels, Nylas follows the provider rules:
- Adding one of the All Mail, Trash, or Spam labels removes the other two.
- Adding either the Trash or Spam label removes the Inbox label.
- Adding the Inbox label removes a message's Trash or Spam labels. It also re-adds the All Mail label if needed.
Deleting messages
Nylas does not directly delete messages on the provider. Instead, Nylas moves the message to the Trash folder or adds the Trash label to the message. The provider usually "empties" the Trash - deletes all messages in that folder or with that label - after a configured period. This allows the user to restore the message by removing the label or moving it out of the Trash folder, and prevents scripts from mass-deleting messages.
Files
Files are any data attached to messages. Nylas allows you to download existing attachments from messages and threads, as well as upload new files to be sent.
Drafts
Drafts are a special kind of message that haven't 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.