# Request Parameters

# **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   |
| ----- | ------ | ----------------------------- | ------------- |
| email | 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:

```json
"headers": {
  "X-Campaign-ID": "promo-2026",
  "X-Client-Reference": "order-12345"
}
```
```yaml
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.

> **Note:** 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 angular brackets, 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

```json
{
  "subject": "Re: Your inquiry",
  "inReplyTo": "<20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>"
}
```
```yaml
subject: "Re: Your inquiry"
inReplyTo: "<20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>"
```