How to Set Up Custom Email Headers in Warmy

Add, edit, and manage custom headers for your mailboxes — directly from the Warmy dashboard, without using the API or contacting support.

What are custom headers?

Custom headers are additional fields added to the technical header section of an email that travel with every message your mailbox sends. They're commonly used for purposes like tracking (for example, GPM tracking) and SMTP-level security.

Custom headers have always been supported in Warmy at the API level — now you can manage them yourself, right inside the product, at the mailbox level.

Once set, a custom header applies to all emails sent from that mailbox — including warm-up emails, placement checker emails, and any other messages.

Сustom headers are applied only to emails sent by Warmy after you've configured them. They're added going forward — to warm-up emails, placement checker emails, and all other messages sent from that mailbox through Warmy. Emails sent before the header was set up are not affected. 

How custom headers work in Warmy

• You choose the header name from a pre-approved list, and you set the value yourself.
• If you need a header name that isn't in the list, reach out to our support team to have it added.
• If you add a header with a name that already exists on the mailbox, the new value replaces the old one when you save.

Managing custom headers for a single mailbox

Open the mailbox you want to configure and go to its custom headers section. From there you can:

1. View — see all custom headers currently configured for the mailbox.
2. Add — choose a header name from the list, enter your value, and save.
3. Edit — change the value of an existing header and save.
4. Remove — delete a header you no longer need.

Changes take effect on emails sent after you save.

Setting custom headers in bulk

If you manage many mailboxes, you can apply custom headers to multiple mailboxes at once. There are two ways to do it.

Option 1 — Via the UI (same value for many mailboxes)

Best when you want to apply the same header and value across many mailboxes.

1. Filter and select the mailboxes you want to update.
2. Choose a header name from the list.
3. Enter the value to apply.
4. Apply — the header is set on all selected mailboxes.

If a selected mailbox already has that header, its value is overwritten. Any mailboxes that can't be updated are reported as failures.

Option 2 — Via file upload (different values per mailbox) 

Best when different mailboxes need different header values. You upload a CSV file, and Warmy applies each row to the matching mailbox.

Your CSV should include these columns:

• id — the mailbox ID (optional if email is provided)
• email — the mailbox email address (optional if id is provided)
• header — the custom header name (must be from the allowed list)
• value — the value for that header

You can identify mailboxes by id, by email, or both. Example formats:

Option 3 - Via the API

 Besides the UI, you can also manage custom headers programmatically through the Warmy API. This is useful if you want to automate header configuration as part of your own workflow or scripts.

To get started, you'll need an API key — see How to generate an API Key in Warmy.

The same rules apply: header names must be from the allowed list, and if a header with the same name already exists on a mailbox, its value is overwritten. 

id,email,header,value 42,my@example.com,X-GPM-ID,campaign-123 43,another@example.com,X-GPM-ID,campaign-456

id,header,value 42,X-GPM-ID,campaign-123 43,X-GPM-ID,campaign-456

email,header,value my@example.com,X-GPM-ID,campaign-123 another@example.com,X-GPM-ID,campaign-456

How results are handled:

• If a mailbox already has the header, the value is overwritten and logged as successful.
• If a header name isn't in the allowed list, that row fails with a clear reason (for example, "Header name is not allowed").
• If a mailbox can't be updated (for example, missing details or permissions), it's logged as a failure.

Which method to choose

• File upload — the most flexible option; ideal for large setups where different mailboxes need different values.
• UI — faster when you want the same header and value applied across many mailboxes.