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:

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:

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

Retrieve Sent Email Introduction Usage & Rate Limits Send test emails

⌘I