Drafts

Drafts represent messages that have been composed, but not yet sent. The Nylas Email API uses the same commands to manage drafts across providers, and can refer to specific drafts using the provider's draft_id.

The /drafts endpoints allow you to create and save drafts without sending them immediately. A draft may contain all components of a standard message, including recipients, a subject, body content, and attachments. The endpoints offer full Create, Read, Update, and Delete (CRUD) functions.

Adding attachments to drafts

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

When you add attachments to a draft, the format you use depends on the total size of the HTTP payload of your message. If the total size is more than 3MB, you must use the multipart/form-data schema. This format is subject to provider limits of 25MB for the full request.

Metadata on drafts

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

Drafts scopes

The table below lists the Drafts 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.

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

Query IMAP server directly

Set the query_imap query parameter to true in your Get Draft or Get all Drafts 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 Drafts request, Nylas includes the specified folder ID only in the returned drafts' folder fields, even if the draft 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 draft, or you're also using the has_attachment query parameter, your request can take even longer.

EWS query considerations

You must enable search indexing for all mailboxes on your on-premises Microsoft Exchange server configuration for Nylas query parameters to work correctly.