Request Parameters
Marketing Email
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| from | Address | Yes | Sender's email address and name |
| replyTo | Address | No | Reply-to email address and name |
| to | Address[] | Yes | List of primary recipients |
| cc | Address[] | No | List of CC recipients |
| bcc | Address[] | No | List of BCC recipients |
| subject | string | Yes | Email subject line |
| html | string | Yes (html or text) | HTML email content |
| text | string | Yes (html or text) | Plain text email content |
| attachments | Attachment[] | No | List of file attachments |
| customerReference | string | No | Your reference for tracking |
| inReplyTo | string | No | Message-ID of the email being replied to. Enables threading in email clients. |
| headers | object | No | Custom key-value email headers to include in the outbound message. Check Custom Headers section below. |
Objects
Address
| Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Email address | |
| name | string | No (Required for From object) | Display name |
Attachment
| Field | Type | Required | Description |
|---|---|---|---|
| fileName | string | Yes | Name of the file with extension |
| content | string | Yes | Base64 encoded file content |
| contentType | string | Yes | MIME type of the file |
| contentId | string | No | Content ID for inline images |
Supported File Types
| Category | Extensions |
|---|---|
| Images | .jpg, .jpeg, .png |
| Documents | .pdf, .doc, .docx |
| Archives | .zip |
Custom Headers
Custom headers let you attach metadata to outgoing emails that email clients and servers can act on — without it appearing in the message body. A few common uses:
- Prevent Gmail from threading unrelated emails together using
X-Entity-Ref-ID - Add a one-click unsubscribe shortcut with
List-Unsubscribe - Pass internal tracking references like campaign or order IDs
The headers field accepts a flat key-value JSON object:
"headers": {
"X-Campaign-ID": "promo-2026",
"X-Client-Reference": "order-12345"
}
headers:
X-Campaign-ID: "promo-2026"
X-Client-Reference: "order-12345"
| Rule | Detail |
|---|---|
| Format | JSON object {"key": "value"} — not an array |
| Maximum entries | 20 headers |
| Name format | Letters, digits, and hyphens only. Must start and end with a letter or digit (e.g. X-Custom-Header) |
| Value format | Printable ASCII characters only. Max 998 characters |
| Reserved headers | System headers (From, To, Bcc, Subject, Message-ID, DKIM-Signature, etc.) cannot be overridden |
Requests that violate these rules are rejected with a 400 Bad Request error.
If you set In-Reply-To through custom headers, you must also provide the References header alongside it — email clients rely on both headers to thread the message correctly. For most cases, prefer the dedicated inReplyTo field.
Email Threading (inReplyTo)
Use inReplyTo to thread outbound emails into existing conversations in recipients' email clients.
Finding the Message-ID of the original email
The Message-ID of an outbound email includes a timestamp, the message UUID, and the sending domain:
Message-ID: <20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>
To get this value, view the raw source of the email in your client. In Gmail: open the email, click the three-dot menu, and select Show original.
First-level reply
{
"subject": "Re: Your inquiry",
"inReplyTo": "<20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>"
}
subject: "Re: Your inquiry"
inReplyTo: "<20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>"
Transactional Email
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| priority | string | Yes | "low" or "high" |
| Priority | Description | Use Cases |
|---|---|---|
| high | Time-sensitive, critical emails | Password resets, OTP, urgent alerts |
| low | Standard transactional emails | Order confirmations, receipts |
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| from | Address | Yes | Sender's email address and name |
| replyTo | Address | No | Reply-to email address and name |
| to | Address[] | Yes | List of primary recipients |
| cc | Address[] | No | List of CC recipients |
| bcc | Address[] | No | List of BCC recipients |
| subject | string | Yes | Email subject line |
| html | string | Yes (html or text) | HTML email content |
| text | string | Yes (html or text) | Plain text email content |
| attachments | Attachment[] | No | List of file attachments |
| customerReference | string | No | Your reference for tracking |
| inReplyTo | string | No | Message-ID of the email being replied to. Enables threading in email clients. |
| headers | object | No | Custom key-value email headers to include in the outbound message. Check Custom Headers section below. |
Objects
Address
| Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Email address | |
| name | string | No (Required for From object) | Display name |
Attachment
| Field | Type | Required | Description |
|---|---|---|---|
| fileName | string | Yes | Name of the file with extension |
| content | string | Yes | Base64 encoded file content |
| contentType | string | Yes | MIME type of the file |
| contentId | string | No | Content ID for inline images |
Supported File Types
| Category | Extensions |
|---|---|
| Images | .jpg, .jpeg, .png |
| Documents | .pdf, .doc, .docx |
| Archives | .zip |
Custom Headers
Custom headers let you attach metadata to outgoing emails that email clients and servers can act on — without it appearing in the message body. A few common uses:
- Prevent Gmail from threading unrelated emails together using
X-Entity-Ref-ID - Add a one-click unsubscribe shortcut with
List-Unsubscribe - Pass internal tracking references like campaign or order IDs
The headers field accepts a flat key-value JSON object:
"headers": {
"X-Campaign-ID": "promo-2026",
"X-Client-Reference": "order-12345"
}
headers:
X-Campaign-ID: "promo-2026"
X-Client-Reference: "order-12345"
| Rule | Detail |
|---|---|
| Format | JSON object {"key": "value"} — not an array |
| Maximum entries | 20 headers |
| Name format | Letters, digits, and hyphens only. Must start and end with a letter or digit (e.g. X-Custom-Header) |
| Value format | Printable ASCII characters only. Max 998 characters |
| Reserved headers | System headers (From, To, Bcc, Subject, Message-ID, DKIM-Signature, etc.) cannot be overridden |
Requests that violate these rules are rejected with a 400 Bad Request error.
If you set In-Reply-To through custom headers, you must also provide the References header alongside it — email clients rely on both headers to thread the message correctly. For most cases, prefer the dedicated inReplyTo field.
Email Threading (inReplyTo)
Use inReplyTo to thread outbound emails into existing conversations in recipients' email clients.
Finding the Message-ID of the original email
The Message-ID of an outbound email includes a timestamp, the message UUID, and the sending domain:
Message-ID: <20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>
To get this value, view the raw source of the email in your client. In Gmail: open the email, click the three-dot menu, and select Show original.
First-level reply
{
"subject": "Re: Your inquiry",
"inReplyTo": "<20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>"
}
subject: "Re: Your inquiry"
inReplyTo: "<20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>"