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.
references	string	No	Space-separated list of Message-IDs forming the full thread chain. Used for deep thread display. Falls back to inReplyTo value if omitted.
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:

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

Email Threading (inReplyTo / references)

Use inReplyTo and references 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.

Note: The inReplyTo value must match the Message-ID exactly, including the timestamp prefix and angle brackets. The UUID from the API response messageId field alone will not work.

First-level reply

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

Deep thread (reply to a reply)

Include the full chain of Message-IDs in references, space-separated in chronological order:

{
  "subject": "Re: Your inquiry",
  "inReplyTo": "<20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>",
  "references": "<[email protected]> <20260617052825.68047ebb-f07f-48bb-a504-f4dc42d073c1@yourdomain.com>"
}