Tags and headers
Label emails with tags to find them and route their webhooks, and add your own email headers.
Tags
Tags come back in every webhook for the email, and filter
the log — in the dashboard and with GET /v1/emails?tag=type:invoice. Send
them as an object:
{ "tags": { "type": "order_confirmation", "store": "erbil" } }or as an array of name/value pairs:
{ "tags": [{ "name": "type", "value": "order_confirmation" }, { "name": "store", "value": "erbil" }] }Either way they come back as an object.
- Up to 10 tags per email, each name once.
- Names and values use letters, digits,
_and-only, up to 256 characters each. - A few names are reserved for our own use and refused:
category,workspaceId,apiEmailId,emailSendId,outboundEmailId(in any case). - Tags are labels, not data: an order id is fine, personal details are not.
Good uses
| Tag | Why |
|---|---|
type: password_reset | See bounce rates per kind of email; route webhooks in your handler. |
user_id: 1842 | Find every email a customer got. |
env: staging | Tell environments apart in one workspace. |
Headers
{
"headers": {
"X-Entity-Ref-ID": "order-4821",
"List-Unsubscribe": "<https://myapp.example/notifications/off?u=1842>",
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
}
}- Up to 20 headers per email, each name once (in any case).
- Names are printable ASCII without a colon, up to 76 characters. Values are ASCII, up to 998 characters, with no line breaks — encode anything else (RFC 2047) first.
X-Entity-Ref-IDwith a unique value stops Gmail from threading separate emails (such as two sign-in codes) into one conversation.List-UnsubscribeandList-Unsubscribe-Post(one-click unsubscribe, RFC 8058) are allowed — right for product notices a person can switch off, like a weekly activity summary. Your URL must turn the notice off when it receives the POST. A workspace where most emails carry these headers looks like a mailing list (how we check).- Reserved (we set them):
From,To,Cc,Bcc,Subject,Reply-To,Sender,Date,Return-Path,Message-ID,MIME-Version,Content-*,DKIM-*,X-SES-*. Setting one answersvalidation_error; use the request's own fields (from,to,reply_to, …) instead.