Messages

The Nylas Send API allows you to send messages immediately, and schedule them to be sent in the future (asynchronously). You can save scheduled messages either in Nylas, or as Draft objects on the provider. The Send API uses the same commands to manage messages across all providers, and can refer to specific messages using the provider's message_id.

Nylas uses webhooks to let you know when an email message has been sent. The webhook's message includes a status, a reason description, and the Nylas request ID. For more information, see the notifications documentation.

Adding attachments to messages

Use the Messages endpoints to add and modify files attached to email messages as you send them. The Attachments APIs allow you to download or get the metadata about an existing attachment, but you use the Messages API to add or modify the attachments. For more information, see Working with email attachments.

Provider IDs for messages

Nylas uses an object's provider ID to refer to the object, and different providers return differently formatted IDs. For IMAP messages, Nylas extracts the ID from the message-id header. For Google and Microsoft, the object ID comes from the provider's internal ID.

Metadata on messages

You can add metadata to new and existing messages by including the metadata sub-object in your POST, PUT, or PATCH request. For more information, see the Metadata documentation.

Messages scopes

The table below lists the Messages endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.

The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.

No scopes are required for the /messages/schedules endpoints, because scheduled messages are stored with Nylas. You will need gmail.send or Mail.ReadWrite to send scheduled messages, however.

For more information about scopes, see Using scopes to request user data.

Messages notifications

You can subscribe to the following triggers so Nylas notifies you about changes to your users' data:

• message.created
• message.updated

You can subscribe to the following triggers to get notifications about the status of a scheduled message:

• message.send_success
• message.send_failed
• message.bounce_detected (Available for Google, Microsoft Graph, iCloud, and Yahoo.)

To receive message notifications, you must enable specific scopes that allow Nylas to monitor for these events. For more information, see the Message notification schemas.

Message tracking and send status monitoring

You can configure options to track when a message you sent has been opened, when links inside of it are clicked, and when someone replies to a thread. For more information, see the message tracking documentation.

Nylas includes a message.bounce_detected notification for Google, Microsoft Graph, iCloud, and Yahoo that triggers when a message that you send bounces. You can subscribe to the trigger to monitor for bounced messages.

You can use the message.send_success and message.send_failed triggers to monitor the status of messages that you send using Scheduled Send. For these triggers to work, you must set the send_at parameter in your Send Message request. For more information, see Schedule messages to send in the future.

Search messages

Search for messages by making a GET /v3/grants/<NYLAS_GRANT_ID>/messages request that includes any of the following query parameters:

• subject, thread_id
• any_email, to, from, cc, bcc
• received_before, received_after
• in, unread, starred, has_attachment
• search_query_native
• fields

The search_query_native parameter allows you to add provider-specific query strings to your request for Google, Microsoft Graph, and EWS accounts. The value that you specify must be URL-encoded.

For more information and a list of provider considerations, see Searching with Nylas.

Query IMAP server directly

Set the query_imap query parameter to true in your Get Message or Get all Messages requests to query the IMAP server directly instead of the Nylas database. This lets you get the most up-to-date information from the IMAP server, or data older than the default three-month retention time.

When you use the query_imap query parameter in a Get all Messages request, you must also set the in query parameter. This tells Nylas which folder to query. Nylas includes the specified folder ID only in the returned messages' folder fields, even if the message is in multiple folders.

Keep in mind that most IMAP servers are slow and have low rate limits. Nylas might take more time to return responses compared to requests that don't use the query_imap query parameter. If an account has many folders, you're querying for a large message, or you're also using the has_attachment query parameter, your request can take even longer.

Sometimes, you might receive a 404 error for valid message IDs. This is because some IMAP servers don't support searching for email headers.