---
title: "Send a transactional email"
method: POST
path: "/v3/domains/{domain_name}/messages/send"
tags: ["Transactional send"]
---

# Send a transactional email

`POST /v3/domains/{domain_name}/messages/send`

Sends a message from the specified domain. You can track deliverability (delivered, bounced, complaint, rejected) using [Nylas' notifications](/docs/reference/notifications/#transactional-email-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.

<div id="admonition-info">💡 <b>Emails landing in spam?</b> Consider <a href="/docs/v3/agent-accounts/domain-warming/">warming up your email domain</a> to improve deliverability.</div>

## Request body

- object
  - `attachments` object[] — An array of files to be sent with the message.
    - `content` string — The Base64-encoded file content. See [Working with email attachments](/docs/v3/email/attachments/#attachment-schemas-and-size-limits) for more information.
    - `content_disposition` string — (Not supported for Microsoft and EWS) The content disposition of the file. Usually, this is `inline` or `attachment`, followed by the file name.
    - `content_id` string — (Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the HTML message body. To avoid unexpected behavior in threads, make sure to use unique CIDs across messages of a thread.
    - `content_type` string — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the file. This is used by the email client to determine how to display the attachment.
    - `filename` string — The file name.
  - `bcc` object[] — A list of people to be BCC'd on the message.
    - `email` string — The recipient's email address.
    - `name` string — The recipient's name.
  - `body` string — The HTML-formatted body of the message.
  - `cc` object[] — A list of people to be CC'd on the message.
    - `email` string — The recipient's email address.
    - `name` string — The recipient's name.
  - `custom_headers` object[] — An array of custom headers to add to the message.
    - `name` string — The header name.
    - `value` string — The header value.
  - `from` object, required — Information about the person sending the message.
    - `email` string — The sender's email address. Must belong to an email domain that's been verified with Nylas.
    - `name` string — The sender's name.
  - `is_plaintext` boolean — 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.
  - `metadata` Metadata — The metadata associated with the object. For more information, see [Metadata](/docs/reference/api/#metadata).
  - `reply_to` object[] — A list of people who should receive replies to the message by default.
    - `name` string — The name of the person who should receive replies to the message.
    - `email` string — The email address of the person who should receive replies to the message.
  - `reply_to_message_id` string — 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](https://datatracker.ietf.org/doc/html/rfc822#section-4.6.1) `Message-ID` header of the message you're replying to.
  - `send_at` integer — 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.
  - `subject` string — The subject line of the message.
  - `template` object — The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
    - `id` string — The template ID.
    - `strict` boolean — When `true`, Nylas returns an error if the template contains variables that aren't defined in the `variables` object.
    - `variables` object — A set of key/value pairs representing variables to substitute for values in the template.
  - `to` object[], required — A list of recipients for the message.
    - `email` string — The recipient's email address.
    - `name` string — The recipient's name.
  - `tracking_options` object — Tracking settings for the message. See [Track messages](/docs/v3/email/message-tracking/).
    - `opens` boolean — When `true`, enables [message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the message. Nylas generates a [`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications) when a participant first opens the message.
    - `links` boolean — When `true`, enables [link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the message. Nylas generates a [`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications) when a participant clicks a link in the message.
    - `label` string — A brief description of the message, why it's being tracked, or the tracking options enabled.
    - `domain_name` string — The custom hostname to use for link click and message open tracking. The hostname must be registered to the authenticated organization in the [Nylas Dashboard](https://dashboard-v3.nylas.com/organization/domains?tab=hosted-auth) and have an active certificate. Custom tracking hostnames are available on select plans. Contact your Nylas account representative or the [Nylas Sales team](https://www.nylas.com/contact-sales/) to enable this feature for your organization. Nylas trims surrounding whitespace, removes one trailing dot, and converts ASCII letters to lowercase before looking up the hostname. Provide an ASCII fully qualified hostname without a URL scheme, path, port, or wildcard. You must enable `links`, `opens`, or both when you provide this field. A custom tracking hostname does not support `thread_replies` by itself. If you omit this field, Nylas uses its regional tracking hostname. Invalid, inactive, blocked, deleted, and unowned hostnames return the same generic `400` response. If Nylas cannot complete the explicit ownership and certificate lookup, it returns a `5xx` response without falling back to a Nylas hostname.

## Response `200`

Success. Returns message.

- object
  - `data` TransactionalSendMessage
    - `id` string — The message ID.
    - `attachments` AttachmentTransactionalSend[] — An array of Attachment objects. For google, linked Google Drive files are not included. For Microsoft, linked One Drive files are not included.
      - `content_type` string — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the attachment, used by the email client to determine how to display the attachment. If you don't provide a type, Nylas infers it from the file name. The value of this field is exactly the same as the email attachment's `Content-Type` header. The provider might set additional parameters, such as `name` and `charset`. Nylas returns an empty `content_type` field if an attachment file name contains non-ASCII characters (for example, accented characters like `ü`). This is because Google can't detect its content type.
      - `filename` string — The file name of the attachment.
      - `content_id` string — (Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the message's HTML. For example, you might see something like `<img src=\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\">` in the message body. Sometimes, the `content_id` value is contained in angle brackets (for example, `<ce9b9547-9eeb-43b2-ac4e-58768bdf04e4>`).
      - `content_disposition` string — (Not supported for Microsoft and EWS) The content disposition of the attachment. Usually, this is `inline` or `attachment` followed by the file name (for example, `inline; filename="some-image.jpeg"`).
      - `is_inline` boolean — If `true`, indicates that the attachment is an inline file.
      - `size` integer — The size of the attachment, in bytes.
    - `bcc` MessageParticipant[] — An array of name/email address pairs that the message was BCC'd to. For received messages, this is nearly always empty.
      - `name` string
      - `email` string, email, required
    - `body` string — The body of the message. This field is the same as the `body` field in your request.
    - `cc` MessageParticipant[] — An array of name/email address pairs that the message was CC'd to.
      - `name` string
      - `email` string, email, required
    - `from` MessageParticipantResponse[] — A list of name/email address pairs that the message was sent from. For transactional send, this will always be one pair.
      - `name` string
      - `email` string, email
    - `object` string — The object type of the response (in this case, `message`).
    - `reply_to` MessageParticipant[] — An array of name/email address pairs that should receive replies to the message.
      - `name` string
      - `email` string, email, required
    - `snippet` string — 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.
    - `subject` string — The subject of the message.
    - `tracking_options` object — Tracking options for the message.
      - `opens` boolean — When `true`, shows that message open tracking is enabled.
      - `links` boolean — When `true`, shows that link clicked tracking is enabled.
      - `label` string — A label describing the message tracking purpose.
    - `to` MessageParticipant[] — An array of name/email address pairs that the message was sent to.
      - `name` string
      - `email` string, email, required
  - `request_id` string — The request ID.

## Other responses

- `400` — Bad Request
- `409` — Conflict. Returned when an `Idempotency-Key` conflicts with an existing entry.

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)