Custom headers & List-Unsubscribe
Attach your own SMTP headers with customHeaders, add a one-click List-Unsubscribe experience, and tag messages with a label. These fields are part of the same POST /transactional-email payload.
PrerequisiteThis builds on Send your first email (HTTP API). You need a Bearer token and a verified authorized sender.
Custom headers
customHeaders is an array of { "name", "value" } objects.
| Rule | Value |
|---|---|
| Max headers per message | 10 |
name length | 1–60 characters |
"customHeaders": [
{ "name": "X-Campaign-Id", "value": "welcome-2026" },
{ "name": "X-Entity-Ref-Id", "value": "order-8842" }
]One-click List-Unsubscribe
Bulk and marketing senders should offer one-click unsubscribe (RFC 8058). Add two standard headers via customHeaders:
List-Unsubscribe— amailto:address and/or an HTTPS URL, each wrapped in angle brackets and comma-separated.List-Unsubscribe-Post— set toList-Unsubscribe=One-Clickso mailbox providers can unsubscribe the recipient with a single POST, no confirmation page required.
curl -X POST 'https://connect.routee.net/transactional-email' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"from": { "name": "Acme", "address": "[email protected]" },
"to": [{ "address": "[email protected]" }],
"subject": "This month at Acme",
"content": { "html": "<p>Here is what is new this month.</p>" },
"label": "newsletter-2026-07",
"customHeaders": [
{
"name": "List-Unsubscribe",
"value": "<mailto:[email protected]>, <https://yourdomain.com/unsubscribe?u=abc123>"
},
{
"name": "List-Unsubscribe-Post",
"value": "List-Unsubscribe=One-Click"
}
]
}'import requests
payload = {
"from": {"name": "Acme", "address": "[email protected]"},
"to": [{"address": "[email protected]"}],
"subject": "This month at Acme",
"content": {"html": "<p>Here is what is new this month.</p>"},
"label": "newsletter-2026-07",
"customHeaders": [
{
"name": "List-Unsubscribe",
"value": "<mailto:[email protected]>, <https://yourdomain.com/unsubscribe?u=abc123>",
},
{"name": "List-Unsubscribe-Post", "value": "List-Unsubscribe=One-Click"},
],
}
resp = requests.post(
"https://connect.routee.net/transactional-email",
headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN", "Content-Type": "application/json"},
json=payload,
)
print(resp.status_code, resp.json())
Why it mattersA working one-click unsubscribe improves inbox placement and is required by major mailbox providers for bulk senders. Make sure both the
mailto:and HTTPS endpoints actually process the unsubscribe.
Tag messages with label
labellabel (max 80 characters) is a free-form tag you attach to a send — for example a campaign name or message type. Use it to group and filter messages when you review tracking data.
"label": "password-reset"Field reference
- Custom Headers Object Explained
- Full reference: Send a transactional email
Next steps
- Delivery Status Notifications (DSN) & footers — add unsubscribe footers and delivery notifications
- Track delivery & receive callbacks — confirm delivery and engagement
- Schedule & control delivery — send later and bound retries