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

# Custom headers and metadata

# Custom Headers and Metadata

Mailofly allows you to specify custom RFC 2822 email headers and metadata for threading, tracking, and compliance.

***

## Custom Headers

You can include any custom headers using the `headers` parameter:

```typescript theme={null}
await mailofly.emails.send({
  from: "Support <support@acme.com>",
  to: ["customer@example.com"],
  subject: "Re: Ticket #4812",
  html: "<p>We have updated your ticket.</p>",
  headers: {
    "In-Reply-To": "<original-message-id@mail.gmail.com>",
    "References": "<original-message-id@mail.gmail.com>",
    "X-Entity-Ref-ID": "ticket_4812",
    "List-Unsubscribe": "<https://acme.com/unsubscribe?id=123>, <mailto:unsub@acme.com>"
  },
});
```

### Common Header Use Cases

* **`In-Reply-To` & `References`**: Keep transactional emails grouped inside the same email conversation thread in Gmail and Outlook.
* **`List-Unsubscribe` & `List-Unsubscribe-Post`**: Enables the native one-click "Unsubscribe" button at the top of Gmail and Apple Mail headers.
* **`X-Custom-Tracking-ID`**: Pass custom internal IDs to correlate incoming webhook events back to your database.

***

## Metadata & Tags

Instead of custom headers, you can pass structured JSON key-value pairs in the `tags` property:

```typescript theme={null}
await mailofly.emails.send({
  from: "App <noreply@acme.com>",
  to: ["user@example.com"],
  subject: "Your Weekly Digest",
  html: "<p>Here is your weekly summary.</p>",
  tags: {
    environment: "production",
    campaign: "weekly_digest",
    user_id: "usr_987654",
  },
});
```

These tags are stored with the message record and echoed back in all webhook events (`email.delivered`, `email.clicked`, `email.bounced`), making it simple to process analytics downstream.


## Related topics

- [Custom Headers](/sending/custom-headers.md)
- [Retrieve Sent Email](/api/emails/retrieve-email.md)
- [Properties](/audience/properties.md)
- [Introduction](/audience/introduction.md)
- [Return Path](/domains/return-path.md)