Send a transactional email - Transactional Send - API Reference

POST

https://api.us.nylas.com/v3/domains/{domain_name}/messages/send

Sends a message from the specified domain. You can track deliverability (delivered, bounced, complaint, rejected) using Nylas' notifications.

The route's domain_name value is the verified sender domain. To use a different custom hostname for link click or message open tracking, provide tracking_options.domain_name in the request body. For example, you can send from sender.example.com and track through tracking.example.com. Nylas validates scheduled custom tracking hostnames when you create the schedule and revalidates them immediately before delivery. If an explicit hostname is no longer eligible, the send fails without falling back to a Nylas hostname.

💡 Emails landing in spam? Consider warming up your email domain to improve deliverability.

NYLAS API KEYACCESS TOKEN

Parameters

Path parameters

domain_name*string

The verified sender domain Nylas will send the message from. This path parameter is separate from tracking_options.domain_name, which selects the hostname for link click and message open tracking.

Example: "sender.example.com"

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 Nylas application (not per domain -- a key collides across all verified domains under the same application). 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 to be BCC'd on the message.

bodystring

The HTML-formatted body of the message.

Example: "Looking forward to seeing you!"

ccarray<object>

A list of people to be CC'd on the message.

custom_headersarray<object>

An array of custom headers to add to the message.

from*object

Information about the person sending the message.

is_plaintextboolean

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

Default: false

Example: true

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 are replying to. If you are using a message that was sent using Nylas' Transactional Send, you may use the ID that was returned in the Nylas response. For all other messages, 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. 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. If the request includes tracking_options.domain_name, Nylas validates the hostname when it creates the schedule and revalidates it before delivery.

subjectstring

The subject line 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 recipients for the message.

tracking_optionsobject

Tracking settings for the message. See Track messages.

Responses

dataobject

idstring

The message ID.

Example: "6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb"

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}]

minItems: 0

bccarray<object>

An array of name/email address pairs that the message was BCC'd to. For received messages, this is nearly always empty.

bodystring

The body of the message. This field is the same as the body field in your request.

Example: "Hello, I just sent a message using Nylas!"

ccarray<object>

An array of name/email address pairs that the message was CC'd to.

fromarray<object>

A list of name/email address pairs that the message was sent from. For transactional send, this will always be one pair.

objectstring

The object type of the response (in this case, message).

Example: "message"

reply_toarray<object>

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

snippetstring

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

Example:

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

minLength: 1

subjectstring

The subject of the message.

Example: "Nylas Send v3 Email"

tracking_optionsobject

Tracking options for the message.

toarray<object>

An array of name/email address pairs that the message was sent to.

request_idstring

The request ID.

Example: "9ca1d434-5ac7-4331-b8fb-3749c9a758d3"

Send a transactional emailBeta