Send a Draft - Drafts - API Reference

POST

https://api.us.nylas.com/v3/grants/{grant_id}/drafts/{draft_id}

Sends the specified draft as a message. You can optionally include a signature_id to append a signature to the message body at send time.

Queued sends on Agent Accounts

When an Agent Account sends faster than its per-second rate limit, Nylas can queue the draft instead of rejecting it, and returns 202 Accepted with the draft object. Queued drafts are sent in order, usually within seconds. A draft at the back of a full queue can take up to 90 seconds. Subscribe to message.delivered to confirm that a queued draft went out, and to message.send_failed to learn if it couldn't be sent. A draft that fails to send stays in the Drafts folder. See Send queueing.

Works with an API key, an access token (use /v3/grants/me/ in place of the grant ID), or an IAM API key with the drafts.send permission.

Parameters

Path parameters

grant_id*string

ID of the grant to access. Use /me/ to refer to the grant associated with an access token.

draft_id*string

ID of the draft to access. Nylas recommends you URL-encode this field, or you might receive a 404 error if the ID contains special characters (for example, #).

Query parameters

selectstring

Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at). This allows you to receive only the portion of object data that you're interested in. You can use select to optimize response size and reduce latency by limiting queries to only the information that you need.

Request body

signature_idstring

The ID of a signature to append to the message body when sending. Nylas inserts the signature after a line break at the end of the body, including after any quoted text. Only use this if the draft was created without a signature, or if you want to add one at send time.

Example: "sig_abc123"

Responses

request_idstring

The request ID.

dataobject

A draft of a message. You can edit a draft until you send it as a message.

bccarray<object>

The name/email address pairs of the recipients to be BCC'd.

bodystring

The body of the draft as either plain-text or HTML content. If the draft has both plain-text and HTML, Nylas returns the HTML version.

Example: "Hi, Welcome to Nylas!"

ccarray<object>

The name/email address pairs of the recipients to be CC'd.

attachmentsarray<object>

An array of Attachment objects. For Google, linked Google Drive files are not included. For Microsoft, linked One Drive files are not included.

Example:

[{"content_disposition":"attachment","content_type":"text/calendar","id":"4kj2jrcoj9ve5j9yxqz5cuv98","size":1708},{"content_disposition":"attachment","content_type":"application/ics","filename":"invite.ics","id":"70jcsv367jaiavt4njeu4xswg","size":1708}]

foldersarray<string>

A list of folder IDs. For Microsoft, only a single folder is supported. For Google, multiple folders may exist.

Example: ["8l6c4d11y1p4dm4fxj52whyr9","d9zkcr2tljpu3m4qpj7l2hbr0"]

fromarray<object>

An array containing a single name/email address pair, to set as the From header.

Example: [{"email":"[email protected]","name":""}]

grant_idstringread-only

The ID of grant for the connected user.

Example: "41009df5-bf11-4c97-aa18-b285b5f2e386"

idstring

A globally unique object identifier for Microsoft accounts. An email address for Google accounts.

Example: "5d3qmne77v32r8l4phyuksl2x, [email protected]"

minLength: 1

metadataobject

The metadata associated with the object. For more information, see Metadata.

objectstring

The object type of the response. In this case, draft.

Example: "draft"

reply_toarray<object>

An array of name/email address pairs that should receive replies to the message.

Example: [{"email":"[email protected]","name":""}]

snippetstring

A short snippet of the message body (the first 100 characters, with any HTML tags removed). This is useful for displaying a preview of a draft message.

Example:

"You have been invited to the following event. Welcome! WhenThu Oct 28, 2021 7am - 8am Eastern\nTime - Toronto Joining info"

minLength: 1

starredboolean

When true, shows that the Draft has been starred by the user. For EWS, this is only supported for Microsoft Exchange 2010 or later.

Example: false

subjectstring

The subject line of the draft.

Example: "Invitation: Welcome! @ Thu Oct 28, 2021 7am - 8am (EDT) - Toronto"

thread_idstring

A reference to the parent Thread object. If this is a new draft, the thread is empty.

Example: "1t8tv3890q4vgmwq6pmdwm8qg"

toarray<object>

The name/email address pairs of the recipients.

Example: [{"email":"[email protected]","name":""},{"email":"[email protected]","name":""}]

minItems: 1

Send queued. An Agent Account returns 202 when it sends faster than its per-second rate limit and Nylas queues the draft to send shortly after. The response has the same draft object as a 200. See Send queueing.

request_idstring

The request ID.

dataobject

A draft of a message. You can edit a draft until you send it as a message.

bccarray<object>

The name/email address pairs of the recipients to be BCC'd.

bodystring

The body of the draft as either plain-text or HTML content. If the draft has both plain-text and HTML, Nylas returns the HTML version.

Example: "Hi, Welcome to Nylas!"

ccarray<object>

The name/email address pairs of the recipients to be CC'd.

attachmentsarray<object>

An array of Attachment objects. For Google, linked Google Drive files are not included. For Microsoft, linked One Drive files are not included.

Example:

[{"content_disposition":"attachment","content_type":"text/calendar","id":"4kj2jrcoj9ve5j9yxqz5cuv98","size":1708},{"content_disposition":"attachment","content_type":"application/ics","filename":"invite.ics","id":"70jcsv367jaiavt4njeu4xswg","size":1708}]

foldersarray<string>

A list of folder IDs. For Microsoft, only a single folder is supported. For Google, multiple folders may exist.

Example: ["8l6c4d11y1p4dm4fxj52whyr9","d9zkcr2tljpu3m4qpj7l2hbr0"]

fromarray<object>

An array containing a single name/email address pair, to set as the From header.

Example: [{"email":"[email protected]","name":""}]

grant_idstringread-only

The ID of grant for the connected user.

Example: "41009df5-bf11-4c97-aa18-b285b5f2e386"

idstring

A globally unique object identifier for Microsoft accounts. An email address for Google accounts.

Example: "5d3qmne77v32r8l4phyuksl2x, [email protected]"

minLength: 1

metadataobject

The metadata associated with the object. For more information, see Metadata.

objectstring

The object type of the response. In this case, draft.

Example: "draft"

reply_toarray<object>

An array of name/email address pairs that should receive replies to the message.

Example: [{"email":"[email protected]","name":""}]

snippetstring

A short snippet of the message body (the first 100 characters, with any HTML tags removed). This is useful for displaying a preview of a draft message.

Example:

"You have been invited to the following event. Welcome! WhenThu Oct 28, 2021 7am - 8am Eastern\nTime - Toronto Joining info"

minLength: 1

starredboolean

When true, shows that the Draft has been starred by the user. For EWS, this is only supported for Microsoft Exchange 2010 or later.

Example: false

subjectstring

The subject line of the draft.

Example: "Invitation: Welcome! @ Thu Oct 28, 2021 7am - 8am (EDT) - Toronto"

thread_idstring

A reference to the parent Thread object. If this is a new draft, the thread is empty.

Example: "1t8tv3890q4vgmwq6pmdwm8qg"

toarray<object>

The name/email address pairs of the recipients.

Example: [{"email":"[email protected]","name":""},{"email":"[email protected]","name":""}]

minItems: 1