Skip to main content
{
  "from": {
    "email": "[email protected]",
    "name": "Support Team"
  },
  "to": [
    {
      "email": "[email protected]",
      "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": "[email protected]",
      "name": "Support Team"
    },
    "to": [
      {
        "email": "[email protected]",
        "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": "[email protected]",
    "name": "Order Confirmation"
  },
  "to": [
    {
      "email": "[email protected]"
    }
  ],
  "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": "[email protected]",
    "name": "Marketing Team"
  },
  "to": [
    {
      "email": "[email protected]"
    }
  ],
  "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": "[email protected]",
    "name": "Notifications"
  },
  "to": [
    {
      "email": "[email protected]"
    }
  ],
  "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.