Skip to main content

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.

{
  "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.