Skip to content
Skip to main content
POST
/v3/grants/{grant_id}/messages/send

Send a Message

Sends the specified message. If you want to send the message immediately, omit the send_at field from your request. If you want to schedule it to be sent later, set send_at to the time you want to send the message, in seconds using the Unix timestamp format.

For more information about scheduling messages, see Schedule messages to send in the future.

(Google and Microsoft Graph only) When scheduling a message, you can set use_draft to true to save the message in the user's Drafts folder until it's sent.

Nylas also supports sending raw MIME messages. For more information, see Send messages with MIME data.

Limitations

Microsoft Graph and iCloud don't support the List-Unsubscribe-Post or List-Unsubscribe headers.

NYLAS API KEYACCESS TOKEN

Parameters

Path parameters

grant_id*string

ID of the grant to access. You can also use the email address associated with the grant, or use /me/ to refer to the grant associated with an access token.

Example: "nyla@example.com"

Query parameters

fieldsstring

Include message headers in the send response. Headers are returned in the same headers array format as Get Message responses.

  • standard: Returns the standard send response (no headers array).
  • include_headers: Returns the full set of headers on the response.
  • include_basic_headers: Returns only the three RFC threading headers (Message-ID, In-Reply-To, References). Use this option when you only need to track message identity and thread relationships — payload size is significantly smaller than include_headers.

Supported on synchronous send only. The parameter has no effect when you set the send_at field on the request (scheduled send is asynchronous and doesn't return headers).

For provider support details, see Using email headers and MIME data.

standardinclude_headersinclude_basic_headers
Default: "standard"

Header parameters

Idempotency-Keystring

A unique, client-generated key (max 256 characters) that lets you safely retry this send request without sending duplicate emails. Nylas caches the response (success or error) for 1 hour, scoped per grant. A retry with the same key and payload returns the cached response with the Idempotent-Response: true header set. See Idempotent send requests for the full retry behavior and error responses.

Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

Request body

Content-Type: application/json, multipart/form-data
attachmentsarray<object>

An array of files to be sent with the message.

bccarray<object>

A list of people BCC'd on the message.

bodystring

The HTML body of the message.

Example: "Looking forward to seeing you!"
ccarray<object>

A list of people CC'd on the message.

custom_headersarray<object>

An array of custom headers to add to the message.

fromarray<object>
is_plaintextboolean

When true, the message body is sent as plain text and the MIME data doesn't include the HTML version of the message. When false, the message body is sent as HTML.

Default: false
metadataobject

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

reply_toarray<object>

A list of people who should receive replies to the message by default.

reply_to_message_idstring

The ID of the message you're replying to. For Gmail and Microsoft Graph, this is the message ID on the provider. For IMAP Send, this is the RFC822 Message-ID header of the message you're replying to.

send_atinteger

The time when Nylas should send the message, in seconds using the Unix timestamp format. This time must be at least one minute in the future from the time you make your request. You can schedule a message to be sent up to 30 days in the future.

subjectstring

The subject of the message.

Example: "Reminder: Annual Philosophy Club Meeting"
templateobject

The template to use for the message. Can be overriden by the body and subject fields.

to*array<object>

A list of people that the message will be sent to.

tracking_optionsobject

Tracking settings for the message. See Track messages.

use_draftboolean

(Google and Microsoft only) When true, Nylas saves the message in the user's Drafts folder until its send_at time. This field can't be true if send_at is undefined.

Default: false
signature_idstring

The ID of a signature to append to the message body. Nylas inserts the signature after a line break at the end of the body, including after any quoted text in replies and forwards. Only one signature can be used per message.

Example: "sig_abc123"

Responses

grant_id*string
request_id*string
data*object
POSThttps://api.us.nylas.com/v3/grants/nyla%40example.com/messages/send?fields=standard

Find your API key in the Nylas Dashboard under API Keys in your application settings.

grant_idrequiredstring

ID of the grant to access. You can also use the email address associated with the grant, or use /me/ to refer to the grant associated with an access token.

fieldsstring

Include message headers in the send response. Headers are returned in the same headers array format as Get Message responses. - standard: Returns the standard send response (no headers array). - include_headers: Returns the full set of headers on the response. - include_basic_headers: Returns only the three RFC threading headers (Message-ID, In-Reply-To, References). Use this option when you only need to track message identity and thread relationships — payload size is significantly smaller than include_headers. Supported on synchronous send only. The parameter has no effect when you set the send_at field on the request (scheduled send is asynchronous and doesn't return headers). For provider support details, see Using email headers and MIME data.

Loading editor...

Autocomplete and validation come from this endpoint's request schema.