SendPost Webhook Object

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.

Complete Webhook Payload Structure

Every webhook payload sent by SendPost follows this structure:

{
  "event": {
    "eventID": "string",
    "type": "integer",
    "messageID": "string",
    "submittedAt": "integer",
    "smtpCode": "integer",
    "smtpDescription": "string",
    "eventMetadata": {
      "clickedURL": "string",
      "smtpCode": "integer",
      "smtpDescription": "string",
      "userAgent": {
        "Family": "string",
        "Major": "string",
        "Minor": "string",
        "Patch": "string"
      },
      "os": {
        "Family": "string",
        "Major": "string",
        "Minor": "string",
        "Patch": "string",
        "PatchMinor": "string"
      },
      "device": {
        "Family": "string",
        "Brand": "string",
        "Model": "string"
      },
      "geo": {
        "city": "string",
        "country": "string",
        "countryCode": "string",
        "region": "string",
        "regionCode": "string",
        "postalCode": "string",
        "latitude": "number",
        "longitude": "number",
        "timezone": "string"
      },
      "trackedIP": "string",
      "rawUserAgent": "string"
    }
  },
  "emailMessage": {
    "messageID": "string",
    "from": {
      "email": "string",
      "name": "string"
    },
    "to": [
      {
        "email": "string",
        "name": "string"
      }
    ],
    "subject": "string",
    "emailType": "string",
    "ipID": "integer",
    "ipPoolID": "integer",
    "ipPool": "string",
    "publicIP": "string",
    "headers": {
      "key": "value"
    },
    "groups": ["string"]
  }
}

Event Object Fields

The event object contains information about the specific webhook event that occurred.

Field	Type	Description	Present In
`eventID`	string	Unique identifier for this specific event. Use this to deduplicate events if your webhook endpoint receives the same event multiple times due to retries.	All events
`type`	integer	Numeric code indicating the type of event. See the Event Types table below for all possible values.	All events
`messageID`	string	Unique identifier for the email message. This ID remains consistent across all events for the same email, allowing you to correlate events throughout the email lifecycle.	All events
`submittedAt`	integer	Unix timestamp (in seconds) indicating when this specific event occurred in SendPost. For example, when the email was processed, delivered, opened, or clicked. Use this to track the exact timing of each event in the email lifecycle.	All events
`smtpCode`	integer	The SMTP response code returned by the recipient’s mail server. Common codes: 200-299 (success), 400-499 (temporary failure), 500-599 (permanent failure).	Delivered, SoftBounced, HardBounced
`smtpDescription`	string	Human-readable description of the SMTP response. Provides context about why an email was delivered, bounced, or rejected.	Delivered, SoftBounced, HardBounced
`eventMetadata`	object	Contains additional metadata specific to the event type. The fields present vary depending on the event type.	All events (contents vary)

Event Types

Every event generated as SendPost webhook will have a type field in the event object:

Webhook Event	Type Field Value	Description
Processed	0	Email has been accepted by SendPost and is queued for delivery
Dropped	1	Email was not sent due to suppression list, invalid recipient, or policy violation
Delivered	2	Email was successfully delivered to the recipient’s mail server
SoftBounced	3	Email delivery temporarily failed; SendPost will retry delivery
HardBounced	4	Email delivery permanently failed; the recipient address is invalid or doesn’t exist
Opened	5	Recipient opened the email (requires tracking pixel)
Clicked	6	Recipient clicked a link in the email (requires link tracking)
Unsubscribed	7	Recipient unsubscribed via the unsubscribe link
Spam	8	Recipient marked the email as spam

Event Metadata Fields

The eventMetadata object contains event-specific information. Different fields are populated depending on the event type.

Field	Type	Description	Present In
`clickedURL`	string	The full URL that the recipient clicked. Only present when a link click is tracked.	Clicked
`smtpCode`	integer	Duplicate of `event.smtpCode` for convenience. The SMTP response code from the recipient’s mail server.	Delivered, SoftBounced, HardBounced
`smtpDescription`	string	Duplicate of `event.smtpDescription` for convenience. Human-readable SMTP response description.	Delivered, SoftBounced, HardBounced
`userAgent`	object	Parsed user agent information identifying the email client or browser used to open/click.	Opened, Clicked
`os`	object	Parsed operating system information of the device used to open/click.	Opened, Clicked
`device`	object	Parsed device information identifying the hardware used to open/click.	Opened, Clicked
`geo`	object	Geographic location information based on the IP address of the recipient when they opened/clicked.	Opened, Clicked
`trackedIP`	string	The IP address of the recipient when they clicked a link.	Clicked
`rawUserAgent`	string	The raw, unparsed User-Agent string from the recipient’s browser or email client.	Opened, Clicked

userAgent Object Fields

The userAgent object provides parsed browser/email client information:

Field	Type	Description	Example
`Family`	string	Name of the browser or email client	”Chrome”, “Safari”, “Outlook”, “Gmail”
`Major`	string	Major version number of the browser/client	”91”, “15”, “16”
`Minor`	string	Minor version number of the browser/client	”0”, “4”, “2”
`Patch`	string	Patch version number of the browser/client	”4472”, “1”, “0”

os Object Fields

The os object provides parsed operating system information:

Field	Type	Description	Example
`Family`	string	Name of the operating system	”Windows”, “Mac OS X”, “iOS”, “Android”, “Linux”
`Major`	string	Major version number of the OS	”10”, “14”, “12”
`Minor`	string	Minor version number of the OS	”0”, “5”, “1”
`Patch`	string	Patch version number of the OS	”19041”, “1”, “0”
`PatchMinor`	string	Additional patch version detail (if available)	“1”

device Object Fields

The device object provides parsed hardware device information:

Field	Type	Description	Example
`Family`	string	General category or name of the device	”iPhone”, “iPad”, “Samsung”, “Other”
`Brand`	string	Brand/manufacturer of the device	”Apple”, “Samsung”, “Google”, “Unknown”
`Model`	string	Specific model of the device	”iPhone 13”, “Galaxy S21”, “Pixel 6”

geo Object Fields

The geo object provides geographic location information based on IP geolocation:

Field	Type	Description	Example
`countryCode`	string	ISO 3166-1 alpha-2 country code	”US”, “GB”, “DE”
`regionCode`	string	Region/state code	”CA”, “NY”, “TX”
`postalCode`	string	Postal or ZIP code	”94102”, “10001”, “SW1A 1AA”
`timezone`	string	IANA timezone identifier	”America/Los_Angeles”, “Europe/London”

Geographic data is derived from IP address lookups and may not always be 100% accurate. The precision depends on the IP geolocation database and the nature of the recipient’s network connection.

Email Message Object Fields

The emailMessage object contains information about the original email that was sent. This object remains identical across all webhook events for the same email.

Field	Type	Description	Present In
`messageID`	string	Unique identifier for the email message. Matches `event.messageID` and can be used to correlate events across the email lifecycle.	All events
`from`	object	The sender information for the email. Contains the sender’s email address and display name.	All events
`to`	array	Array of recipient objects. Each object contains the recipient’s email address and display name.	All events
`subject`	string	The subject line of the email as it was sent.	All events
`emailType`	string	The classification type of the email. Common values include `transactional` for system-generated emails (receipts, password resets, notifications) and `marketing` for promotional content. This helps distinguish email purposes for analytics and compliance.	All events
`ipID`	integer	The unique identifier of the specific IP address used to send this email. Use this to track which IP was used for delivery, useful for troubleshooting deliverability issues.	All events
`ipPoolID`	integer	The unique identifier of the IP pool from which the sending IP was selected. IP pools group multiple IPs together for load balancing and reputation management.	All events
`ipPool`	string	The name of the IP pool used for sending this email. This is the human-readable name assigned to the IP pool, making it easier to identify which pool was used without looking up the ID.	All events
`publicIP`	string	The actual public IP address used by SendPost to deliver this email to the recipient’s mail server. This is the IP that receiving servers see and is important for monitoring sender reputation.	All events
`headers`	object	Key-value pairs of custom headers that were included in the original email request. Use these for tracking campaigns, orders, or custom metadata.	All events (if headers were sent)
`groups`	array	Array of group names/tags that were assigned to the email for classification and filtering purposes.	All events (if groups were assigned)

from Object Fields

The from object contains sender information:

Field	Type	Description	Example
`email`	string	The email address of the sender	”[email protected]”
`name`	string	The display name of the sender (shown in email clients)	“Support Team”, “John Doe”

to Array Item Fields

Each item in the to array represents a recipient:

Field	Type	Description	Example
`email`	string	The email address of the recipient	”[email protected]”
`name`	string	The display name of the recipient	”John Doe”, “Jane Smith”

headers Object

The headers object is a key-value store for custom headers:

Field	Type	Description	Example
`{key}`	string	Any custom header key you included in your email request	`"X-Campaign-Id": "summer-2024"`

Custom headers you send with your email are preserved and returned in all webhook events. This allows you to track emails throughout their lifecycle using your own identifiers.

groups Array

The groups array contains classification tags:

Field	Type	Description	Example
`groups[n]`	string	A group/tag name assigned to categorize the email	”transactional”, “marketing”, “order-confirmation”

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 Type	smtpCode Available	smtpDescription Available	Location in Payload
Processed (0)	❌ No	❌ No	N/A
Dropped (1)	❌ No	❌ No	N/A
Delivered (2)	✅ Yes	✅ Yes	`event.smtpCode`, `event.smtpDescription`, `event.eventMetadata.smtpCode`, `event.eventMetadata.smtpDescription`
SoftBounced (3)	✅ Yes	✅ Yes	`event.smtpCode`, `event.smtpDescription`, `event.eventMetadata.smtpCode`, `event.eventMetadata.smtpDescription`
HardBounced (4)	✅ Yes	✅ Yes	`event.smtpCode`, `event.smtpDescription`, `event.eventMetadata.smtpCode`, `event.eventMetadata.smtpDescription`
Opened (5)	❌ No	❌ No	N/A
Clicked (6)	❌ No	❌ No	N/A
Unsubscribed (7)	❌ No	❌ No	N/A
Spam (8)	❌ No	❌ No	N/A

Common SMTP Codes

Code Range	Category	Description
200-299	Success	Email was accepted and delivered successfully
250	Success	Requested mail action completed
421	Temporary	Service not available, try again later
450	Temporary	Mailbox unavailable (busy or temporarily blocked)
451	Temporary	Local error in processing
452	Temporary	Insufficient storage
500	Permanent	Syntax error, command unrecognized
550	Permanent	Mailbox unavailable (not found or policy rejection)
551	Permanent	User not local
552	Permanent	Message size exceeds limit
553	Permanent	Mailbox name not allowed
554	Permanent	Transaction failed

Example: Delivered Event with SMTP Code

{
  "event": {
    "eventID": "edhg-123gh-afasdf-124egh",
    "type": 2,
    "messageID": "mjhl-1401-sasdf-129324",
    "submittedAt": 1704067200,
    "smtpCode": 250,
    "smtpDescription": "email delivered successfully",
    "eventMetadata": {
      "smtpCode": 250,
      "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",
    "emailType": "transactional",
    "ipID": 42,
    "ipPoolID": 7,
    "ipPool": "transactional-pool",
    "publicIP": "192.0.2.100",
    "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",
    "submittedAt": 1704067200,
    "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",
    "emailType": "transactional",
    "ipID": 42,
    "ipPoolID": 7,
    "ipPool": "transactional-pool",
    "publicIP": "192.0.2.100",
    "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.

Example: Opened Event with Full Metadata

{
  "event": {
    "eventID": "evt-789gh-bfasdf-567egh",
    "type": 5,
    "messageID": "mjhl-1401-sasdf-129324",
    "submittedAt": 1704067200,
    "eventMetadata": {
      "userAgent": {
        "Family": "Chrome",
        "Major": "91",
        "Minor": "0",
        "Patch": "4472"
      },
      "os": {
        "Family": "Mac OS X",
        "Major": "10",
        "Minor": "15",
        "Patch": "7"
      },
      "device": {
        "Family": "Mac",
        "Brand": "Apple",
        "Model": "MacBook Pro"
      },
      "geo": {
        "city": "San Francisco",
        "country": "United States",
        "countryCode": "US",
        "region": "California",
        "regionCode": "CA",
        "postalCode": "94102",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "timezone": "America/Los_Angeles"
      },
      "trackedIP": "203.0.113.42",
      "rawUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
    }
  },
  "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",
    "emailType": "marketing",
    "ipID": 15,
    "ipPoolID": 3,
    "ipPool": "marketing-pool",
    "publicIP": "192.0.2.50",
    "headers": {
      "X-Campaign-Id": "summer-sale-2024",
      "X-Customer-Segment": "VIP"
    },
    "groups": ["transactional", "welcome-series"]
  }
}

Example: Clicked Event with URL

{
  "event": {
    "eventID": "evt-101gh-cfasdf-890egh",
    "type": 6,
    "messageID": "mjhl-1401-sasdf-129324",
    "submittedAt": 1704067200,
    "eventMetadata": {
      "clickedURL": "https://example.com/products/summer-sale?utm_source=email&utm_campaign=summer-2024",
      "userAgent": {
        "Family": "Safari",
        "Major": "15",
        "Minor": "4"
      },
      "os": {
        "Family": "iOS",
        "Major": "15",
        "Minor": "4"
      },
      "device": {
        "Family": "iPhone",
        "Brand": "Apple",
        "Model": "iPhone 13"
      },
      "geo": {
        "city": "New York",
        "country": "United States",
        "countryCode": "US",
        "region": "New York",
        "regionCode": "NY",
        "postalCode": "10001",
        "latitude": 40.7128,
        "longitude": -74.0060,
        "timezone": "America/New_York"
      },
      "trackedIP": "198.51.100.78",
      "rawUserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.4 Mobile/15E148 Safari/604.1"
    }
  },
  "emailMessage": {
    "messageID": "mjhl-1401-sasdf-129324",
    "from": {
      "email": "[email protected]",
      "name": "Example Marketing"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "Jane Smith"
      }
    ],
    "subject": "Don't Miss Our Summer Sale!",
    "emailType": "marketing",
    "ipID": 15,
    "ipPoolID": 3,
    "ipPool": "marketing-pool",
    "publicIP": "192.0.2.50",
    "headers": {
      "X-Campaign-Id": "summer-sale-2024",
      "X-Campaign-Type": "promotional"
    },
    "groups": ["marketing", "summer-campaign"]
  }
}

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",
    "submittedAt": 1704067200,
    "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",
    "emailType": "transactional",
    "ipID": 42,
    "ipPoolID": 7,
    "ipPool": "transactional-pool",
    "publicIP": "192.0.2.100",
    "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

Show child attributes

emailMessage

object

Show child attributes

Response

200

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

API Reference

Email

Domain

Stats

Suppression

IP

Message

IPPools

Stats (A)

Sub-Account

Webhook

Complete Webhook Payload Structure

Event Object Fields

Event Types

Event Metadata Fields

userAgent Object Fields

os Object Fields

device Object Fields

geo Object Fields

Email Message Object Fields

from Object Fields

to Array Item Fields

headers Object

groups Array

SMTP Code and Description in Webhook Events

Availability by Event Type

Common SMTP Codes

Example: Delivered Event with SMTP Code

Example: HardBounced Event with SMTP Code

Example: Opened Event with Full Metadata

Example: Clicked Event with URL

Custom Headers in Webhook Payloads

How Headers are Preserved

Example: Email Request with Custom Headers

Example: Webhook Payload with Preserved Headers

Use Cases for Custom Headers

Body

Response

API Reference

Email

Domain

Stats

Suppression

IP

Message

IPPools

Stats (A)

Sub-Account

Webhook

​Complete Webhook Payload Structure

​Event Object Fields

​Event Types

​Event Metadata Fields

​userAgent Object Fields

​os Object Fields

​device Object Fields

​geo Object Fields

​Email Message Object Fields

​from Object Fields

​to Array Item Fields

​headers Object

​groups Array

​SMTP Code and Description in Webhook Events

​Availability by Event Type

​Common SMTP Codes

​Example: Delivered Event with SMTP Code

​Example: HardBounced Event with SMTP Code

​Example: Opened Event with Full Metadata

​Example: Clicked Event with URL

​Custom Headers in Webhook Payloads

​How Headers are Preserved

​Example: Email Request with Custom Headers

​Example: Webhook Payload with Preserved Headers

​Use Cases for Custom Headers

Body

Response

Complete Webhook Payload Structure

Event Object Fields

Event Types

Event Metadata Fields

userAgent Object Fields

os Object Fields

device Object Fields

geo Object Fields

Email Message Object Fields

from Object Fields

to Array Item Fields

headers Object

groups Array

SMTP Code and Description in Webhook Events

Availability by Event Type

Common SMTP Codes

Example: Delivered Event with SMTP Code

Example: HardBounced Event with SMTP Code

Example: Opened Event with Full Metadata

Example: Clicked Event with URL

Custom Headers in Webhook Payloads

How Headers are Preserved

Example: Email Request with Custom Headers

Example: Webhook Payload with Preserved Headers

Use Cases for Custom Headers