> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendpost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Headers

> Pass custom key-value pairs in email requests to track campaigns, customers, and events. Headers are included in all webhook events for easy reconciliation.

```json theme={null}
{
  "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:

```json theme={null}
{
  "headers": {
    "Account-ID": "acc_123456",
    "User-ID": "user_789",
    "Plan-Type": "enterprise"
  }
}
```

### Email Marketing Agencies

Identify campaigns and clients:

```json theme={null}
{
  "headers": {
    "Client-ID": "client_abc",
    "Campaign-ID": "campaign_xyz",
    "Campaign-Type": "newsletter"
  }
}
```

### Email Marketing Platforms

Link emails to contacts and campaigns:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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"
  }
}
```

<Info>
  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.
</Info>

<Info>
  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.
</Info>