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

# Custom headers

> Add application-specific headers to outgoing email

Use the `headers` object to attach custom email headers to a message. Custom headers are useful for correlation IDs, internal workflow metadata, and provider-supported routing hints.

## Add custom headers

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/emails \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: receipt-1234" \
  --data '{
    "to": "ada@example.com",
    "subject": "Your receipt",
    "html": "<p>Your receipt is ready.</p>",
    "headers": {
      "X-Entity-Ref-ID": "order-1234",
      "X-Environment": "production"
    }
  }'
```

## Requirements

A message can include up to 100 custom headers. Header names cannot be empty, and neither names nor values may contain carriage returns or line feeds. The `headers` value must be a JSON object whose values are strings.

Dugble rejects the entire send request when a custom header is invalid.

<Warning>
  Do not put secrets or sensitive personal data in headers. Email headers may be retained by providers and receiving mail systems.
</Warning>

## Use stable names

Use clear application-specific names so logs and downstream systems remain easy to understand:

```json theme={null}
{
  "headers": {
    "X-Entity-Ref-ID": "invoice-9f74",
    "X-Environment": "production"
  }
}
```

Do not use custom headers to replace normal message fields such as `From`, `To`, `Subject`, or `Reply-To`. Set those through the corresponding API fields.

## Batch sends

Custom headers are supported on each message in a batch:

```json theme={null}
[
  {
    "to": "ada@example.com",
    "subject": "Your weekly report",
    "text": "Your report is ready.",
    "headers": {
      "X-Entity-Ref-ID": "report-ada-30"
    }
  },
  {
    "to": "grace@example.com",
    "subject": "Your weekly report",
    "text": "Your report is ready.",
    "headers": {
      "X-Entity-Ref-ID": "report-grace-30"
    }
  }
]
```