Charchy Senddocs

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

TagWhy
type: password_resetSee bounce rates per kind of email; route webhooks in your handler.
user_id: 1842Find every email a customer got.
env: stagingTell 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-ID with a unique value stops Gmail from threading separate emails (such as two sign-in codes) into one conversation.
  • List-Unsubscribe and List-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 answers validation_error; use the request's own fields (from, to, reply_to, …) instead.

On this page