Overview

This page lists examples of the payloads that will be sent to registered transactional email webhooks. The webhook payloads may differ based on the event that triggered it, or whether certain settings have been enabled.

The webhook event type can be one of:

  • sent
  • delivered
  • failed
  • bounce
  • open
  • click
  • unsubscribe
  • resubscribe

The setting field_set can be set to legacy on a webhook to format the webhook payload to match the legacy transactional email callback payloads. With this setting, if the include_html field was set to true, will send the transactional email’s body HTML as part of the webhook payload.

Properties

Properties applicable to all non-legacy payloads

Property Sub-Property Description Data type Parameters
id The webhook payload ID string
type The event type of the webhook enum (string)
  • sent
  • delivered
  • failed
  • bounce
  • click
  • open
  • unsubscribe
  • resubscribe
timestamp The date and time when the webhook was triggered date-time ISO 8601 date-time string
data Array containing the details of the transaction that triggered the webhook Array
  • transaction
transaction id The ID assigned to the transaction when it was generated string
message_id The ID assigned to the message when it was sent string
method The method that was used to send the transaction enum (string)
  • api
  • smtp
group The group that the transaction was sorted in. Default is by month unless a name was provided Array
  • id
  • name
  • id
 The transaction group ID string
  • name
 The name of the group string
sent_timestamp The date and time that the email was sent date-time ISO 8601 date-time string
subject The subject line text of the email string
message_size_bytes The total length of the message in bytes string
recipient The contact who received the email in this event Array
  • name
  • email
  • name
 The shortened name for the recipient string
  • email
 The recipient’s email address string
  • type
 Whether the recipient was a direct recipient or carbon-copied enum (string)
  • to
  • cc
  • bcc
from The email address and name listed as the sender of the email. Array
  • name
  • email
  • name
 The name that will appear as the sender in the recipient’s inbox string
  • email
 The email address that will appear as the sender in the recipient’s inbox string
custom_headers Array containing any custom headers that were sent with the transaction. Null if none were provided Array|null

Properties applicable only to click events

Property Sub-Property Description Data type Parameters
click link The URL that was clicked and recorded string Valid URL
unique_click Whether this was a click from a unique source or a repeated click enum (string)
  • true
  • false

Properties applicable only to bounce events

Property Sub-Property Description Data type Parameters
bounce email The email address that the email bounced from string
received_timestamp The date and time that the email bounced, i.e. when it would have been received by the recipient date-time ISO 8601 date-time string
type The type of bounce that was recorded enum (string)
  • hard
  • soft
  • block
  • auto_responder
  • unidentified
reason The reason that the email bounced string
mime The entire mime that was received from the bounce server, if available, otherwise null string|null

Properties applicable only to open events

Property Sub-Property Description Data type Parameters
open unique_open Whether this open event was recorded from a new source enum (string)
  • true
  • false

Payload example

Payload example for events:

  • sent
  • failed
  • delivered
  • unsubscribe
  • resubscribe
{
        "id": "1234-abcd-5678-efgh",
        "type": "sent",
        "timestamp": "2022-10-17T13:01:00.000Z",
        "data": {
          "transaction": {
            "id": "1234-abcd-5678-efgh",
            "message_id": '1234-abcd',
            "method": "api",
            "group": {
              "id": "1234-abcd-4567-efgh",
              "name": "Default group: 2021-05",
            },
            "sent_timestamp": "2022-10-17T13:01:00.000Z",
            "subject": "Transaction subject",
            "message_size_bytes": "4",
            "recipient": {
              "name": "To",
              "email": "[email protected]",
              "type": "to",
            },
            "from": {
              "name": "From",
              "email": "[email protected]",
            },
            "custom_headers": {
              "X-My-Header": "my header value",
              "X-My-Other_Header": "my other header value",
            },
          },
        },
      }

Payload example

Payload example for event:

  • bounce
{
        "id": "1234-abcd-5678-efgh",
        "type": "bounce",
        "timestamp": "2022-10-17T13:01:00.000Z",
        "data": {
          "transaction": {
            "id": "1234-abcd-5678-efgh",
            "message_id": "1234-abcd",
            "method": "api",
            "group": {
              "id": "1234-abcd-4567-efgh",
              "name": "Default group: 2021-05",
            },
            "sent_timestamp": "2022-10-17T13:01:00.000Z",
            "subject": "Transaction subject",
            "message_size_bytes": "4",
            "recipient": {
              "name": "To",
              "email": "[email protected]",
              "type": "to",
            },
            "from": {
              "name": "From",
              "email": "[email protected]",
            },
            "custom_headers": {
              "X-My-Header": "my header value",
              "X-My-Other_Header": "my other header value",
            },
          },
          "bounce": {
            "email": "[email protected]",
            "received_timestamp": "2022-10-17T13:01:00.000Z",
            "type": "soft",
            "reason": "content-related",
            "mime": null,
          },
        },
      }

Payload example

Payload example for events:

  • click
{
        "id": "1234-abcd-5678-efgh",
        "type": "click",
        "timestamp": "2022-10-17T13:01:00.000Z",
        "data": {
          "transaction": {
            "id": "1234-abcd-5678-efgh",
            "message_id": "1234-abcd",
            "method": "api",
            "group": {
              "id": "1234-abcd-4567-efgh",
              "name": "Default group: 2021-05",
            },
            "sent_timestamp": "2022-10-17T13:01:00.000Z",
            "subject": "Transaction subject",
            "message_size_bytes": "4",
            "recipient": {
              "name": "To",
              "email": "[email protected]",
              "type": "to",
            },
            "from": {
              "name": "From",
              "email": "[email protected]",
            },
            "custom_headers": {
              "X-My-Header": "my header value",
              "X-My-Other_Header": "my other header value",
            },
          },
          "click": {
            "link": "www.link-url.com",
            "unique_click": "true",
          },
        },
      }

Payload example

Payload example for events:

  • open
{
    "id": "1234-abcd-5678-efgh",
        "type": "open",
        "timestamp": "2022-10-17T13:01:00.000Z",
        "data": {
            "transaction": {
            "id": "1234-abcd-5678-efgh",
            "message_id": "1234-abcd",
            "method": "api",
            "group": {
              "id": "1234-abcd-4567-efgh",
              "name": "Default group: 2021-05",
            },
            "sent_timestamp": "2022-10-17T13:01:00.000Z",
            "subject": "Transaction subject",
            "message_size_bytes": "4",
            "recipient": {
              "name": "To",
              "email": "[email protected]",
              "type": "to",
            },
            "from": {
              "name": "From",
              "email": "[email protected]",
            },
            "custom_headers": {
              "X-My-Header": "my header value",
              "X-My-Other_Header": "my other header value",
            },
          },
          "open": {
            "unique_open": "true",
          },
        },
      }

Legacy properties

Properties applicable to all legacy payloads

Property Description Data type Parameters
event_id The ID generated for this event string
event_type The event type that triggered this webhook enum (string)
  • sent
  • delivered
  • failed
  • bounce
  • click
  • open
  • unsubscribe
  • resubscribe
email_to The recipient’s email address string
group_name The group that the transaction was sorted in. Default is by month unless a name was provided string
custom_headers Array containing any custom headers that were sent with the transaction. Null if none were provided Array|null
trans_id The ID assigned to the transaction when it was generated string
message_id The ID assigned to the message when it was sent string
subject The subject line text of the email string
trans_html The HTML body content of the email. Only included if include_html is set to true string
trans_text The text body content of the email string

Properties applicable only to click events

Property Description Data type Parameters
link The URL that was clicked and recorded string Valid URL
unique_click Whether this was a click from a unique source or a repeated click enum (string)
  • yes
  • no

Properties applicable only to bounce events

Property Description Data type Parameters
bounced_email The email address that the email bounced from string
bounced_received_date The time that the bounce was recorded expressed in unix time string
bounce_type The type of bounce that was recorded enum (string)
  • hard
  • soft
  • block
  • auto_responder
  • unidentified
bounce_reason The reason that the email bounced string
trans_bcontent_complete_mime The entire mime that was received from the bounce server, if available, otherwise null string|null

Properties applicable only to open events

Property Sub-Property Description Data type Parameters
open unique_open Whether this open event was recorded from a new source enum (string)
  • true
  • false

Legacy payload example

Payload example for events:

  • sent, with include_html set to true
{
        "event_id": "1234-abcd-5678-efgh",
        "event_date": 1691828611,
        "event_type": "sent",
        "email_to": "[email protected]",
        "group_name": "Default group: 2021-05",
        "custom_headers": {
              "X-My-Header": "my header value",
              "X-My-Other_Header": "my other header value",
            },
        "trans_id": "1234-abcd-5678-efgh",
        "message_id: "1234-abcd",
        "subject: "subject",
        "trans_html": "<html>Transaction body</html>",
        "trans_text": "Transaction body",
      }

Legacy payload example

Payload example for events:

  • sent, with include_html set to false
{
      "event_id": "1234-abcd-5678-efgh",
      "event_date": 1691828611,
      "event_type": "sent",
      "email_to": "[email protected]",
      "group_name": "Default group: 2021-05",
      "custom_headers": {
          "X-My-Header": "my header value",
          "X-My-Other_Header": "my other header value",
        },
      "trans_id": "1234-abcd-5678-efgh",
      "message_id: "1234-abcd",
      "subject: "subject"
}

Legacy payload example

Payload example for events:

  • failed
  • delivered
  • unsubscribe
  • resubscribe
{
      "event_id":"f2caa9fc-6452-49a0-8d9e-17cc063638a6",
      "event_date":1691828611,
      "event_type":"failed",
      "custom_headers":{"X-custom-header":"value1"},
      "trans_id":"58585d51-7530-4313-9a47-41c90fc30ee4",
      "message_id":null,
      "subject":"Testing sent webhook",
      "email_to":"[email protected]",
      "group_name":"Group: August 2023"
    }

Legacy payload example

Payload example for events:

  • bounce
{
      "event_id":"12ad8b6e-b2cb-4c17-947b-480075c25fd7",
      "event_date":1691830555,
      "event_type":"bounce",
      "custom_headers":{"X-custom-header":"value1"},
      "trans_id":"8ec8bec6-dbe2-4b23-b690-e89842bd5693",
      "message_id":null,
      "group_id":1,
      "bounced_email":"[email protected]",
      "bounce_received_date":1691830555,
      "bounce_type":"hard",
      "bounce_reason":"other",
      "trans_bcontent_complete_mime":"smtp;554 Email rejected due to security policies"
    }

Legacy payload example

Payload example for events:

  • click
{
      "event_id":"1160d473-7176-4a3e-a2a0-5acfba32f9f1",
      "event_date":1691830953,
      "event_type":"click",
      "custom_headers":{"X-custom-header":"value1"},
      "trans_id":"4e032b45-ff49-4e29-9311-263a85069ba1",
      "message_id":null,
      "email_to":"[email protected]",
      "group_name":"Group: August 2023",
      "link": "www.link-url.com",
      "unique_click": "yes",
    }

Legacy payload example

Payload example for events:

  • open
{
      "event_id":"1160d473-7176-4a3e-a2a0-5acfba32f9f1",
      "event_date":1691830953,
      "event_type":"open",
      "custom_headers":{"X-custom-header":"value1"},
      "trans_id":"4e032b45-ff49-4e29-9311-263a85069ba1",
      "message_id":null,
      "email_to":"[email protected]",
      "group_name":"Group: August 2023",
      "unique_open": "yes",
    }