# Send a transactional email

> **POST** `https://api.us.nylas.com/v3/domains/{domain_name}/messages/send`

Source: https://developer.nylas.com/docs/reference/api/transactional-send/send-transactional-email/

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

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

**Authentication:** NYLAS_API_KEY, ACCESS_TOKEN

## Parameters

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domain_name` | string | Yes | The domain name Nylas will send the message from. |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Idempotency-Key` | string | No | 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](/docs/v3/email/idempotent-send/) for the full retry behavior and error responses. |

## Request body

Content-Type: application/json, multipart/form-data

- `attachments` (array) - 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` (array) - 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` (array) - 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` (array) - 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` (object) - The metadata associated with the object. For more information, see
[Metadata](/docs/reference/api/#metadata).
- `reply_to` (array) - 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.
- `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` (array) **(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.

## Responses

### 200 - Success. Returns message.

- `data` (object)
  - `id` (string) - The message ID.
  - `attachments` (array) - 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` (array) - 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) **(required)**
  - `body` (string) - The body of the message. This field is the same as the `body` field in your request.
  - `cc` (array) - An array of name/email address pairs that the message was CC'd to.
    - `name` (string)
    - `email` (string) **(required)**
  - `from` (array) - 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)
  - `object` (string) - The object type of the response (in this case, `message`).
  - `reply_to` (array) - An array of name/email address pairs that should receive replies to the message.
    - `name` (string)
    - `email` (string) **(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` (array) - An array of name/email address pairs that the message was sent to.
    - `name` (string)
    - `email` (string) **(required)**
- `request_id` (string) - The request ID.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 409 - Conflict. Returned when an `Idempotency-Key` conflicts with an existing entry.

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/domains/<DOMAIN_NAME>/messages/send' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": [{
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
    }],
    "from": {
        "name": "ACME Support",
        "email": "support@acme.com"
    },
    "subject": "Welcome to ACME",
    "body": "Welcome to ACME! We'\''re here to help you."
}'
```

### Python SDK

```python
from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>",
)

message = nylas.transactional_send.send(
    domain_name="<DOMAIN_NAME>",
    request_body={
        "to": [{"name": "Jane Doe", "email": "jane.doe@example.com"}],
        "from_": {"name": "ACME Support", "email": "support@acme.com"},
        "subject": "Welcome to ACME",
        "body": "Welcome to ACME! We're here to help you.",
    },
)

print(message)

```