Skip to main content

Global Headers

Add custom email headers that are automatically included in every outgoing email sent through Mumara Campaigns.

Navigate to Settings → Global Headers to manage custom headers.

What Are Email Headers?​

Email headers are metadata fields included in every email message. They contain information like sender, recipient, subject, and routing details. Beyond the standard headers (From, To, Subject), you can add custom headers to embed additional information that travels with every email.

Custom headers appear in the email source (viewable via "Show Original" or "View Source" in email clients) and can be read by receiving mail servers, email clients, or downstream processing systems.

Standard headers (handled automatically):

From: sender@example.com
To: recipient@example.com
Subject: Your Newsletter
Date: Sat, 31 Jan 2026 10:00:00 +0000

Custom headers (what you configure here):

X-Campaign-Name: January Newsletter
X-Customer-ID: 12345
X-Mailer: Mumara Campaigns

Why Use Custom Headers?​

Internal Tracking​

Add identifiers that help you track emails through your infrastructure:

HeaderPurpose
X-Campaign-NameIdentify which campaign sent the email
X-Batch-IDGroup emails from the same sending batch
X-EnvironmentDistinguish production vs staging emails

External System Integration​

Pass data to downstream systems that process your emails:

HeaderPurpose
X-CRM-Contact-IDLink back to CRM records
X-Analytics-IDFeed into analytics platforms
X-Webhook-TargetRoute ESP callbacks to specific endpoints

Compliance and Identification​

Meet regulatory or organizational requirements:

HeaderPurpose
X-MailerIdentify your sending system
X-Report-AbuseProvide abuse reporting contact
PrecedenceSignal bulk mail status to receivers

ESP and Deliverability​

Some ESPs and receiving servers use custom headers for special handling:

HeaderPurpose
X-PrioritySet message priority
X-Auto-Response-SuppressPrevent auto-replies
List-Unsubscribe-PostEnable one-click unsubscribe

Viewing Custom Headers​

The page displays all configured headers in a table:

ColumnDescription
KeyThe header name (e.g., X-Campaign-Name)
ValueThe header value
Created OnWhen the header was added
ActionsEdit and delete options via the (...) menu

Page Controls​

  • Add New - Create a new custom header
  • Bulk Actions - Delete multiple selected headers

Adding a Custom Header​

  1. Click Add New
  2. In the modal, enter:
FieldDescription
KeyThe header name (e.g., X-Custom-Header). Only alphanumeric characters and hyphens are supported.
ValueThe header value. Can be any text, including personalization tags.
  1. Click Submit to save, or Reset to clear the form

Key Naming Rules​

  • Use only letters, numbers, and hyphens
  • No spaces or special characters
  • Convention: Start custom headers with X- prefix
  • Case-insensitive (but X-Campaign-Name is more readable than x-campaign-name)

Value Options​

Values can be:

  • Static text: Production, Newsletter, Marketing Team
  • Personalization tags: {{campaign_id}}, {{contact_id}}, {{message_id}}
  • Mixed: Campaign-{{campaign_id}}-{{broadcast_id}}

Editing a Header​

  1. Click the actions menu (...) on the header row
  2. Select Edit
  3. Modify the Key or Value
  4. Click Submit

Deleting Headers​

Single Header​

  1. Click the actions menu (...) on the header row
  2. Select Delete
  3. Confirm deletion

Multiple Headers​

  1. Select headers using the checkboxes
  2. Click Bulk Actions → Delete Selected
  3. Confirm deletion

Practical Examples​

Campaign Identification​

Track which campaign generated each email:

KeyValue
X-Campaign-NameJanuary-Newsletter
X-Campaign-ID{{campaign_id}}
X-Broadcast-ID{{broadcast_id}}

When you analyze bounce logs or ESP callbacks, these headers help you quickly identify the source campaign.

Environment Tagging​

Distinguish emails from different environments:

KeyValue
X-Environmentproduction
X-Sender-Instancemumara-server-01

Useful when running multiple Mumara instances or staging/production environments.

Abuse Handling​

Provide abuse reporting information:

KeyValue
X-Report-Abuseabuse@yourdomain.com
X-Complaints-Topostmaster@yourdomain.com

Some ISPs and spam filters look for these headers when processing abuse reports.

One-Click Unsubscribe (RFC 8058)​

For improved deliverability with major email providers:

KeyValue
List-Unsubscribe-PostList-Unsubscribe=One-Click
note

The List-Unsubscribe header itself is typically managed by sending node configuration or broadcast settings, not global headers. Use global headers for the supporting List-Unsubscribe-Post header if needed.

Global vs Broadcast-Specific Headers​

Global headers (configured here):

  • Applied to ALL emails sent through the system
  • Good for: System identification, environment tags, compliance headers

Broadcast headers (configured per-campaign):

  • Applied only to that specific broadcast
  • Good for: Campaign-specific tracking, A/B test identifiers

If the same header key exists in both global and broadcast settings, the broadcast-specific value typically takes precedence.

Best Practices​

  • Use the X- prefix for custom headers to distinguish them from standard RFC headers
  • Keep headers minimal - Only add headers you actually use; unnecessary headers add to email size
  • Test with email source - Send a test email and view the source to verify headers appear correctly
  • Document your headers - Maintain notes on what each header is for, especially if multiple team members manage campaigns
  • Consider ESP policies - Some ESPs strip or modify certain headers; verify your headers survive delivery

Troubleshooting​

Headers Not Appearing in Emails​

Possible causes:

  • Header not saved (check if it appears in the list)
  • ESP or relay stripping the header
  • Viewing method doesn't show headers

Solutions:

  • Verify the header is listed on the Global Headers page
  • Send a test email and view the full source/original
  • Check with your ESP about header preservation policies
  • Some ESPs strip X- headers; consult their documentation

Invalid Key Format Error​

Cause: Key contains unsupported characters

Solution: Use only alphanumeric characters (A-Z, a-z, 0-9) and hyphens (-). No spaces, underscores, or special characters.

Headers Appear Differently Than Expected​

Possible causes:

  • Personalization tags not resolving
  • Header being modified in transit

Solutions:

  • Verify tag syntax (e.g., {{campaign_id}} not {campaign_id})
  • Check if the tag is supported in header context
  • Test with static values to isolate the issue

Next Steps​

Last updated on