> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# Custom Headers

> Add your own email headers to messages sent with the AhaSend API, use substitutions in header values, and learn which headers AhaSend sets or replaces for you.

Use `headers` in a send request to add your own headers to the email, for example a reference ID your support team can search for, or a header your own systems read on replies.

Available on Free, Pro and Max. See [plans and features](https://ahasend.com/docs/facts.md#plans-and-features).

## How do I add a header?

`headers` is an object of header names and values. A `{{ variable }}` in a value is filled from the recipient's substitutions:

```json theme={null}
{
  "sandbox": true,
  "from": { "email": "orders@yourdomain.com", "name": "Your Store" },
  "recipients": [
    { "email": "customer@example.com", "substitutions": { "order_id": "1001" } }
  ],
  "subject": "Order {{ order_id }} confirmed",
  "text_content": "Thanks for your order.",
  "headers": {
    "X-Order-ID": "{{ order_id }}",
    "X-Entity-Ref-ID": "order-{{ order_id }}"
  }
}
```

## Which rules apply to header names and values?

* A name must be visible ASCII, with no space and no colon. An empty name, or one with a space, a colon or a line break, is rejected.
* A substitution value used in a header must not contain a line break; the request is rejected and the error names the recipient.
* Header values are inserted as they are, without HTML escaping.

## Which headers does AhaSend set for me?

| Header | What happens |
| - | - |
| `Message-ID` | Always generated by AhaSend; a value in `headers` is ignored. The send response returns it as `message_id_header`. |
| `Reply-To` | Use the `reply_to` field. If you set `reply_to`, don't also put `Reply-To` in `headers`. |
| `To` | Set from `recipients`: one recipient per message. For several visible recipients, CC or BCC, use [Create Conversation Message](https://ahasend.com/docs/send-api/multiple-recipients.md#cc-and-bcc). |
| `DKIM-Signature` | Added when the message is signed with your domain's key. |
| `List-Unsubscribe`, `List-Unsubscribe-Post` | Added to mail from a [marketing domain](https://ahasend.com/docs/domains.md#sending-type), and to other mail that uses `{{unsubscribe_url}}`. On that mail, AhaSend keeps your own headers only when they meet the [rules for your own List-Unsubscribe header](https://ahasend.com/docs/campaigns/unsubscribe.md#can-i-use-my-own-list-unsubscribe-header). |

> [!NOTE]
>
> Tracking, tags, retention and sandbox mode have their own fields in the API: see [Tags](https://ahasend.com/docs/send-api/tags.md) and [Tracking and retention per message](https://ahasend.com/docs/send-api/tracking-and-retention.md). Over SMTP, the same settings use [special headers](https://ahasend.com/docs/smtp/special-headers.md).

## Related guides

* [Send email](https://ahasend.com/docs/send-api/send-email.md), [SMTP special headers](https://ahasend.com/docs/smtp/special-headers.md), [Create Message reference](https://ahasend.com/docs/api-reference/messages/create-message.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.