Skip to main content
WEBHOOK
SendPostWebhooks
{
  "event": {
    "eventID": "edhg-123gh-afasdf-124egh",
    "groups": [
      "transactional",
      "user-onboarding"
    ],
    "ipID": 123,
    "ipPoolID": 123,
    "domainID": 123,
    "tpspId": 1,
    "messageType": "default",
    "messageSubject": "Welcome to Pied Piper :) + 1 quick question",
    "accountID": 117,
    "subAccountID": 117,
    "messageID": "mjhl-1401-sasdf-129324",
    "type": 2,
    "from": "[email protected]",
    "fromName": "Richard",
    "to": "[email protected]",
    "toName": "Gavin",
    "submittedAt": 1567512491587205000,
    "smtpCode": 200,
    "smtpDescription": "email delivered successfully",
    "eventMetadata": {
      "smtpCode": 200,
      "smtpDescription": "email delivered successfully",
      "userAgent": {
        "Family": "Mozilla",
        "Major": "5.0",
        "Minor": "0",
        "Patch": "0"
      },
      "os": {
        "Family": "Windows",
        "Major": "10",
        "Minor": "0",
        "Patch": "0",
        "PatchMinor": "0"
      },
      "device": {
        "Family": ""
      },
      "geo": {
        "cityID": "123",
        "continentCode": "EU",
        "countryCode": "US",
        "postalCode": "12345",
        "timeZone": "America/Los_Angeles"
      },
      "clickedURL": "https://hooli.com",
      "trackedIP": "52.34.11.12",
      "rawUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36"
    }
  },
  "emailMessage": {
    "messageID": "mjhl-1401-sasdf-129324",
    "accountID": 117,
    "subAccountID": 117,
    "ipID": 123,
    "publicIP": "52.34.11.12",
    "localIP": "127.0.0.1",
    "emailType": "default",
    "submittedAt": 1567512491587205000,
    "from": {
      "name": "Richard",
      "email": "[email protected]"
    },
    "replyTo": {
      "name": "Gavin",
      "email": "[email protected]"
    },
    "to": [
      {
        "name": "Gavin",
        "email": "[email protected]",
        "customFields": {
          "Company": "Hooli"
        },
        "cc": [
          {
            "name": "Dinesh",
            "email": "[email protected]",
            "customFields": {
              "Company": "Hooli"
            }
          }
        ],
        "bcc": [
          {
            "name": "Jian",
            "email": "[email protected]",
            "customFields": {
              "Company": "Hooli"
            }
          }
        ]
      }
    ],
    "groups": [
      "welcome",
      "user-onboarding"
    ],
    "ipPool": "transactional-piedpiper",
    "headers": {
      "X-Campaign-Id": "12345"
    },
    "customFields": {
      "Company": "Company Name",
      "Email": "[email protected]"
    },
    "trackOpens": true,
    "trackClicks": true,
    "webhookEndpoint": "https://webhook.example.com/webhook"
  }
}
When you use SendPost API to send an email, SendPost generates webhook events throughout the email lifecycle. Each webhook event contains an event object and an emailMessage object. The emailMessage object remains the same across all events for a given email, allowing you to correlate events using the messageID. For a detailed explanation of the email lifecycle and what each event type means, see Understanding Webhook Event Lifecycle. Every event generated as SendPost webhook will have type field in event object:
Webhook EventType Field Value
Processed0
Dropped1
Delivered2
SoftBounced3
HardBounced4
Opened5
Clicked6
Unsubscribed7
Spam8
Below specified are event specific fields. All these fields are contained inside eventMetadata sub-object inside event object. These fields are set for specific webhook events only.
Field TypeEvents for which it is set
clickedURLClicked
smtpCodeDelivered, SoftBounced and HardBounced
smtpDescrptionDelivered, SoftBounced and HardBounced
userAgentOpened and Clicked
osOpened and Clicked
deviceOpened and Clicked
geoOpened and Clicked
trackedIPOpened and Clicked
rawUserAgentOpened and Clicked

​
SMTP Code and Description in Webhook Events

SMTP codes and descriptions provide detailed information about email delivery status. These fields are available in specific webhook events to help you understand delivery outcomes.

​
Availability by Event Type

Event TypesmtpCode AvailablesmtpDescription AvailableLocation in Payload
Processed (0)❌ No❌ NoN/A
Dropped (1)❌ No❌ NoN/A
Delivered (2)✅ Yes✅ Yesevent.smtpCode, event.smtpDescription, event.eventMetadata.smtpCode, event.eventMetadata.smtpDescription
SoftBounced (3)✅ Yes✅ Yesevent.smtpCode, event.smtpDescription, event.eventMetadata.smtpCode, event.eventMetadata.smtpDescription
HardBounced (4)✅ Yes✅ Yesevent.smtpCode, event.smtpDescription, event.eventMetadata.smtpCode, event.eventMetadata.smtpDescription
Opened (5)❌ No❌ NoN/A
Clicked (6)❌ No❌ NoN/A
Unsubscribed (7)❌ No❌ NoN/A
Spam (8)❌ No❌ NoN/A

​
Example: Delivered Event with SMTP Code

{
  "event": {
    "eventID": "edhg-123gh-afasdf-124egh",
    "type": 2,
    "messageID": "mjhl-1401-sasdf-129324",
    "smtpCode": 200,
    "smtpDescription": "email delivered successfully",
    "eventMetadata": {
      "smtpCode": 200,
      "smtpDescription": "email delivered successfully"
    }
  },
  "emailMessage": {
    "messageID": "mjhl-1401-sasdf-129324",
    "from": {
      "email": "[email protected]",
      "name": "Support Team"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "John Doe"
      }
    ],
    "subject": "Welcome to Our Service",
    "headers": {
      "X-Campaign-Id": "12345",
      "X-Custom-Header": "value"
    }
  }
}

​
Example: HardBounced Event with SMTP Code

{
  "event": {
    "eventID": "edhg-456gh-afasdf-124egh",
    "type": 4,
    "messageID": "mjhl-1401-sasdf-129324",
    "smtpCode": 550,
    "smtpDescription": "Mailbox unavailable",
    "eventMetadata": {
      "smtpCode": 550,
      "smtpDescription": "Mailbox unavailable"
    }
  },
  "emailMessage": {
    "messageID": "mjhl-1401-sasdf-129324",
    "from": {
      "email": "[email protected]",
      "name": "Support Team"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "Invalid User"
      }
    ],
    "subject": "Welcome to Our Service",
    "headers": {
      "X-Campaign-Id": "12345"
    }
  }
}
SMTP codes and descriptions are available in both the top-level event object and within event.eventMetadata. Both locations contain the same values for consistency and ease of access.

​
Custom Headers in Webhook Payloads

Any custom headers you include in your email request are preserved and included in all webhook event payloads. This allows you to track campaigns, add custom identifiers, or pass metadata through the entire email lifecycle.

​
How Headers are Preserved

  • Included in All Events: Custom headers sent in your email request are included in the emailMessage.headers object in all webhook events (Processed, Dropped, Delivered, Opened, Clicked, Bounced, Unsubscribed, Spam).
  • Same Across Lifecycle: The headers remain the same across all events for a given email message, allowing you to correlate events using your custom identifiers.
  • Original Format: Headers are returned exactly as you sent them in your email request.

​
Example: Email Request with Custom Headers

{
  "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": {
    "X-Campaign-Id": "summer-sale-2024",
    "X-Order-Id": "ORD-12345",
    "X-Customer-Segment": "VIP"
  }
}

​
Example: Webhook Payload with Preserved Headers

{
  "event": {
    "eventID": "edhg-123gh-afasdf-124egh",
    "type": 5,
    "messageID": "mjhl-1401-sasdf-129324",
    "eventMetadata": {
      "userAgent": {
        "Family": "Chrome",
        "Major": "91"
      },
      "os": {
        "Family": "Windows"
      }
    }
  },
  "emailMessage": {
    "messageID": "mjhl-1401-sasdf-129324",
    "from": {
      "email": "[email protected]",
      "name": "Support Team"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "John Doe"
      }
    ],
    "subject": "Order Confirmation",
    "headers": {
      "X-Campaign-Id": "summer-sale-2024",
      "X-Order-Id": "ORD-12345",
      "X-Customer-Segment": "VIP"
    },
    "groups": ["transactional", "order-confirmation"]
  }
}

​
Use Cases for Custom Headers

Campaign Tracking: 
{
  "headers": {
    "X-Campaign-Id": "summer-sale-2024",
    "X-Campaign-Type": "promotional"
  }
}
Order/Transaction Tracking: 
{
  "headers": {
    "X-Order-Id": "ORD-12345",
    "X-Transaction-Id": "TXN-67890"
  }
}
Customer Segmentation: 
{
  "headers": {
    "X-Customer-Segment": "VIP",
    "X-Customer-Tier": "premium"
  }
}
Custom headers are included in every webhook event for the email, allowing you to filter and process webhooks based on your custom identifiers or metadata.

Body

application/json
​
event
object
​
emailMessage
object

Response

200

Return a 200 status to indicate that the data was received successfully