# Headers and metadata > Add custom email headers and List-Unsubscribe to API sends, see which headers Emailit adds or rewrites, and attach metadata that comes back in webhooks. This page covers two ways to add your own information to an email sent with the Email API: `headers`, which become part of the message the recipient gets, and `meta`, which Emailit stores with the email and returns in the API and in webhooks. It also lists the headers Emailit adds, rewrites or removes. ## Add custom headers Pass `headers` as an object of header names and string values: ```json { "from": "Acme ", "to": "ada@example.com", "subject": "Receipt for order 1042", "text": "Thanks for your order.", "headers": { "X-Entity-Ref-ID": "order-1042", "X-Acme-Account": "881" } } ``` - Use the request fields, not `headers`, for From, To, Cc, Bcc, Reply-To and Subject. - Don't set headers whose names start with `X-Emailit-`. Emailit uses them internally. For example, a message that already contains `X-Emailit-ID` is treated as processed and skips Emailit's header rewriting and DKIM signing. - Headers that Emailit sets itself, such as `Message-ID` and `Date`, are replaced even if you send them. See the next section. ## Headers Emailit adds or changes | Header | What Emailit does | | --- | --- | | `Message-ID` | Sets it to ``, the same value as `message_id` in the send response. A `Message-ID` you provide is replaced. | | `Date` | Sets it when Emailit first processes the message for delivery. | | `Subject` | Writes the final subject and encodes non-ASCII characters. | | `Return-Path` | Sets a bounce address on your return-path subdomain, `emailit.`, so bounces come back to Emailit and SPF aligns. | | `DKIM-Signature` | Signs the message with your domain's DKIM key. A second signature for `emailitmail.com` can be added for complaint feedback loops. | | `Received` | Adds trace headers for the API and the Emailit mail server. | | `X-Emailit-ID` | Adds the email's token. | | `Feedback-ID` | Adds an identifier that mailbox providers use in complaint reports. | | `X-Emailit-Meta` | Adds your `meta` values, base64-encoded, when you send `meta`. | | `X-Emailit-Tracking` | Adds the requested settings when you turn tracking on with `tracking`. | | `Bcc` | Removes it, so Bcc recipients stay hidden. | | `Reply-To` | Removes it when it names the same address as From. | | `Content-Disposition` | Removes it from the top level of the message. Attachment parts keep theirs. | The [SMTP relay](/docs/smtp/headers/) applies the same rewriting to messages you submit over SMTP. ## Add List-Unsubscribe to bulk mail Mailbox providers such as Gmail and Yahoo expect a one-click unsubscribe option on promotional and other bulk mail. [Campaigns](/docs/campaigns/) add one automatically. For newsletters or digests you send through the API, add both headers yourself: ```json { "from": "Acme ", "to": "ada@example.com", "subject": "Acme weekly digest", "html": "

This week at Acme…

", "headers": { "List-Unsubscribe": ", ", "List-Unsubscribe-Post": "List-Unsubscribe=One-Click" } } ``` - The `https` URL must accept a `POST` request with the body `List-Unsubscribe=One-Click` and unsubscribe the person without asking them to confirm (RFC 8058). - Make each URL specific to the recipient, so your endpoint knows who to unsubscribe. - Emailit includes `List-Unsubscribe` and `List-Unsubscribe-Post` in the DKIM signature, which providers require for one-click unsubscribe. See [How do I meet Gmail and Yahoo bulk sender requirements?](/docs/kb/gmail-yahoo-bulk-sender-requirements/) for the other requirements. When someone unsubscribes, stop sending to them. You can add them to your [suppression list](/docs/suppressions/) so Emailit blocks future sends. ## Attach metadata `meta` is an object of string keys and string values that Emailit stores with each email. Use it to connect an email to records in your own system. ```json { "from": "Acme ", "to": "ada@example.com", "subject": "Receipt for order 1042", "text": "Thanks for your order.", "meta": { "order_id": "1042", "customer_id": "cus_881", "kind": "receipt" } } ``` Convert numbers and booleans to strings before you send them. Emailit returns `meta`: - In [Retrieve an email](/docs/api-reference/emails/get/), [Retrieve metadata](/docs/api-reference/emails/meta/) and [List emails](/docs/api-reference/emails/list/). - In webhook events for the email: under `data.object.meta` for `email.accepted`, `email.scheduled`, `email.canceled` and the delivery events, and under `data.object.email.meta` for `email.loaded` and `email.clicked`. A delivery event with metadata looks like this (trimmed): ```json [ { "type": "email.delivered", "data": { "object": { "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa", "object": "email", "to": "ada@example.com", "subject": "Receipt for order 1042", "status": "delivered", "meta": { "order_id": "1042", "customer_id": "cus_881", "kind": "receipt" } } } } ] ``` [Retrying](/docs/email-api/retry-and-forward/) an email keeps its metadata. Forwarding creates a new email without it. > **Metadata travels with the message:** Emailit also writes `meta` into the message as the base64-encoded `X-Emailit-Meta` header, so anyone who views the raw message can decode it. Don't put secrets, tokens or sensitive personal data in `meta`. ## Find emails later You can't search or filter emails by `meta`. To find an email again: - **Store the IDs.** Save the `id`, or the `ids` map for several recipients, next to your own record, and look the email up with [Retrieve an email](/docs/api-reference/emails/get/). - **Filter the list.** [List emails](/docs/api-reference/emails/list/) filters on `to`, `from`, `subject`, `status`, `created_at`, `updated_at`, `spam_score`, `api_key_id` and `sending_domain_id`. See [Filtering](/docs/api-reference/filtering/). - **Use separate API keys.** Give each application or feature its own [API key](/docs/developers/api-keys/), then filter by `api_key_id`, or by **API key** in **Email API → Emails**. - **Match webhook events.** Read `meta` from each event to route it to the right record as it arrives. ## Related - [Send an email](/docs/email-api/send-email/) - [SMTP headers](/docs/smtp/headers/) - [Webhook event types](/docs/webhooks/event-types/) - [Email headers dictionary](/docs/dictionary/email-headers/) --- Source: https://emailit.com/docs/email-api/headers-and-metadata/