Sending

Custom Headers

Custom headers attach metadata to emails for internal tracking, routing, and compliance requirements.

Adding Custom Headers

curl -X POST https://api.postmta.com/v1/messages/send -H "Authorization: Bearer pmta_live_xxxx" -d '{"from":{"address":"hello@shop.example.com"},"to":[{"address":"alice@example.com"}],"subject":"Your order shipped","html":"...","headers":{"X-Customer-ID":"cust_abc123","X-Order-ID":"order_789","X-Campaign-Code":"summer_sale_2026"}}'

Reserved Headers

These headers are set by PostMTA and cannot be overridden:

HeaderDescription
X-PostMTA-Message-IDPostMTA unique message identifier
X-PostMTA-TimestampUTC timestamp of queue acceptance
Return-PathBounce address (envelope MAIL FROM)
DKIM-SignatureDomainKeys Identified Mail signature
Authentication-ResultsSPF, DKIM, DMARC authentication results

Tracking Headers

PostMTA automatically adds tracking headers. Disable per-message:

{"headers":{"X-PostMTA-Track-Opens":"no","X-PostMTA-Track-Clicks":"no"}}

Header Limits