Custom Headers

{
  "from": {
    "email": "support@example.com",
    "name": "Support Team"
  },
  "to": [
    {
      "email": "customer@example.com",
      "name": "John Doe"
    }
  ],
  "subject": "Order Confirmation",
  "htmlBody": "<p>Thank you for your order!</p>",
  "headers": {
    "Contact-ID": "12345",
    "Campaign-ID": "summer-sale-2024",
    "Customer-ID": "CUST-789",
    "Account-ID": "ACC-456"
  },
  "trackOpens": true,
  "trackClicks": true,
  "ippool": "marketing"
}

How It Works

Include a headers object in your email request with any custom key-value pairs. These headers are preserved throughout the email lifecycle and included in all webhook event payloads. When an email is processed, delivered, hard bounced, soft bounced, opened, clicked, unsubscribed, or marked as spam, the webhook event includes your custom headers in the emailMessage.headers object. This makes it easy to reconcile events, update statistics for your customers, or create custom internal dashboards.

Use Cases

SaaS Companies

Track which customer account triggered each email:

{
  "headers": {
    "Account-ID": "acc_123456",
    "User-ID": "user_789",
    "Plan-Type": "enterprise"
  }
}

Email Marketing Agencies

Identify campaigns and clients:

{
  "headers": {
    "Client-ID": "client_abc",
    "Campaign-ID": "campaign_xyz",
    "Campaign-Type": "newsletter"
  }
}

Email Marketing Platforms

Link emails to contacts and campaigns:

{
  "headers": {
    "Contact-ID": "contact_123",
    "Campaign-ID": "campaign_456",
    "List-ID": "list_789"
  }
}

Headers in Webhook Events

Custom headers are included in all webhook event types:

Processed (type: 0)
Dropped (type: 1)
Delivered (type: 2)
SoftBounced (type: 3)
HardBounced (type: 4)
Opened (type: 5)
Clicked (type: 6)
Unsubscribed (type: 7)
Spam (type: 8)

Example: Webhook Payload with Custom Headers

{
  "event": {
    "eventID": "edhg-123gh-afasdf-124egh",
    "type": 5,
    "messageID": "mjhl-1401-sasdf-129324",
    "eventMetadata": {
      "userAgent": {
        "Family": "Chrome",
        "Major": "91"
      }
    }
  },
  "emailMessage": {
    "messageID": "mjhl-1401-sasdf-129324",
    "from": {
      "email": "support@example.com",
      "name": "Support Team"
    },
    "to": [
      {
        "email": "customer@example.com",
        "name": "John Doe"
      }
    ],
    "subject": "Order Confirmation",
    "headers": {
      "Contact-ID": "12345",
      "Campaign-ID": "summer-sale-2024",
      "Customer-ID": "CUST-789",
      "Account-ID": "ACC-456"
    }
  }
}

Examples

Transactional Email with Order Tracking

{
  "from": {
    "email": "orders@example.com",
    "name": "Order Confirmation"
  },
  "to": [
    {
      "email": "customer@example.com"
    }
  ],
  "subject": "Your order has been confirmed",
  "htmlBody": "<p>Thank you for your order!</p>",
  "headers": {
    "Order-ID": "ORD-12345",
    "Customer-ID": "CUST-789",
    "Transaction-ID": "TXN-456"
  }
}

Marketing Campaign with Segmentation

{
  "from": {
    "email": "marketing@example.com",
    "name": "Marketing Team"
  },
  "to": [
    {
      "email": "user@example.com"
    }
  ],
  "subject": "Special Offer Just for You!",
  "htmlBody": "<p>Check out our latest offer!</p>",
  "headers": {
    "Campaign-ID": "summer-sale-2024",
    "Segment-ID": "vip-customers",
    "Agency-Client-ID": "client_abc"
  }
}

Multi-Tenant Application

{
  "from": {
    "email": "notifications@example.com",
    "name": "Notifications"
  },
  "to": [
    {
      "email": "user@example.com"
    }
  ],
  "subject": "Welcome to Our Platform",
  "htmlBody": "<p>Welcome aboard!</p>",
  "headers": {
    "Tenant-ID": "tenant_123",
    "User-ID": "user_456",
    "Workspace-ID": "workspace_789"
  }
}

Custom headers are preserved exactly as you send them. Use consistent naming conventions (e.g., Contact-ID, Campaign-ID) across your application to make webhook processing easier.

Headers are included in every webhook event for a given email, allowing you to filter and process webhooks based on your custom identifiers without needing to store additional mapping data.

Documentation

Guides

SDK Quickstarts

Common Use Cases

How It Works

Use Cases

SaaS Companies

Email Marketing Agencies

Email Marketing Platforms

Headers in Webhook Events

Example: Webhook Payload with Custom Headers

Examples

Transactional Email with Order Tracking

Marketing Campaign with Segmentation

Multi-Tenant Application

​How It Works

​Use Cases

​SaaS Companies

​Email Marketing Agencies

​Email Marketing Platforms

​Headers in Webhook Events

​Example: Webhook Payload with Custom Headers

​Examples

​Transactional Email with Order Tracking

​Marketing Campaign with Segmentation

​Multi-Tenant Application

How It Works

Use Cases

SaaS Companies

Email Marketing Agencies

Email Marketing Platforms

Headers in Webhook Events

Example: Webhook Payload with Custom Headers

Examples

Transactional Email with Order Tracking

Marketing Campaign with Segmentation

Multi-Tenant Application