EmailElement Docs

Webhook Events Reference

Every webhook EmailElement sends is one JSON object describing one thing that happened to one email. This page lists all fourteen events, says when each one fires, and gives the whole payload for every one of them.

Fields

Every value is a JSON string, ids included.

Field Type Description On
type string The event name, the same as the Event column below. every event
createdAt string When the event happened, as yyyy-MM-ddTHH:mm:ss. No offset and no trailing Z — it is UTC. every event
messageId string The run id of this one email to this one recipient. A whole number, sent as a string. every event
recipient string The recipient address. every event
senderDomain.domain string The sender domain the email was sent from. every event
senderDomain.id string Its id. every event
sendIntegration.name string The send integration that carried the email. every event
sendIntegration.id string Its id. every event
esp string The email service provider behind that send integration, for example SendGrid. every event
source string What the email was sent by, as Name [Source] — for example April Newsletter [Scheduled Email]. Source is Scheduled Email, Triggered Sequence or Transactional Email. When the name cannot be found you get the source on its own. every event
sourceId string The id of that scheduled email, triggered sequence or transactional relay. every event
emailContent.name string The Email Content used. every event
emailContent.id string Its id. every event
emailContent.template.name string The template within that Email Content. every event
emailContent.template.id string Its id. every event
emailContent.fromName.name string The From Name used. every event
emailContent.fromName.id string Its id. every event
emailContent.subjectLine.name string The subject line used. every event
emailContent.subjectLine.id string Its id. every event
error.reason string Why the send failed. Failed
bounce.type string soft or hard. SoftBounced, HardBounced
bounce.message string What the receiving server said. SoftBounced, HardBounced
unsubscribe.reason string How the recipient unsubscribed. Unsubscribed
client.ipAddress string The IP the open or click came from. Opened, Clicked
client.userAgent string The browser or mail client that made the request. Opened, Clicked
client.link string The link that was clicked. Clicked
trackId1 … trackId5 string Your own tracking values, from a Transactional Email send. Any that are empty are left out of the payload, so on a send that set none of them these five properties are absent. every event, when set

Event types

ID Event When it fires
1 Paused You paused the send, or it was paused for you.
2 Canceled You cancelled the send.
3 Failed EmailElement could not hand the email to the send integration.
4 Submitted EmailElement handed the email to the send integration.
5 Initiated The send integration accepted the email and is starting to send it.
6 Retry The send integration is trying again after a failure.
7 Sent The send integration confirmed it delivered the email.
8 SoftBounced A temporary failure at the receiving server. It may be retried.
9 HardBounced A permanent failure at the receiving server. The address will not be tried again.
10 Complained The recipient reported the email as spam.
11 Suppressed The email was not sent because the address is on a suppression list.
12 Unsubscribed The recipient unsubscribed.
13 Opened The recipient opened the email.
14 Clicked The recipient clicked a tracked link.

Every event payload

Each example is a send with no tracking values set, which is why none of them shows a trackId. The Transactional Email section below shows one that does.

Paused

You paused the send, or it was paused for you.

{
  "type": "Paused",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  }
}

Canceled

You cancelled the send.

{
  "type": "Canceled",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  }
}

Failed

EmailElement could not hand the email to the send integration. Carries error on top of the common fields.

{
  "type": "Failed",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  },
  "error": {
    "reason": "Send integration returned 401 Unauthorized"
  }
}

Submitted

EmailElement handed the email to the send integration.

{
  "type": "Submitted",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  }
}

Initiated

The send integration accepted the email and is starting to send it.

{
  "type": "Initiated",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  }
}

Retry

The send integration is trying again after a failure.

{
  "type": "Retry",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  }
}

Sent

The send integration confirmed it delivered the email.

{
  "type": "Sent",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  }
}

SoftBounced

A temporary failure at the receiving server. It may be retried. Carries bounce on top of the common fields.

{
  "type": "SoftBounced",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  },
  "bounce": {
    "type": "soft",
    "message": "452 4.2.2 Mailbox full"
  }
}

HardBounced

A permanent failure at the receiving server. The address will not be tried again. Carries bounce on top of the common fields.

{
  "type": "HardBounced",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  },
  "bounce": {
    "type": "hard",
    "message": "550 5.1.1 User unknown"
  }
}

Complained

The recipient reported the email as spam.

{
  "type": "Complained",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  }
}

Suppressed

The email was not sent because the address is on a suppression list.

{
  "type": "Suppressed",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  }
}

Unsubscribed

The recipient unsubscribed. Carries unsubscribe on top of the common fields.

{
  "type": "Unsubscribed",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  },
  "unsubscribe": {
    "reason": "One-click unsubscribe"
  }
}

Opened

The recipient opened the email. Carries client on top of the common fields.

{
  "type": "Opened",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  },
  "client": {
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0 Safari/537.36"
  }
}

Clicked

The recipient clicked a tracked link. Carries client on top of the common fields.

{
  "type": "Clicked",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  },
  "client": {
    "ipAddress": "203.0.113.42",
    "link": "https://yourdomain.com/april-offer",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0 Safari/537.36"
  }
}

Tracking values on a Transactional Email

A Transactional Email send can carry up to five of your own tracking values. They are added to whichever event fires, and any you did not set are removed rather than sent empty:

{
  "type": "Sent",
  "createdAt": "2026-04-02T10:00:00",
  "messageId": "84213907",
  "recipient": "jane@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "412"
  },
  "sendIntegration": {
    "name": "Production SendGrid",
    "id": "78"
  },
  "esp": "SendGrid",
  "source": "April Newsletter [Scheduled Email]",
  "sourceId": "1904",
  "emailContent": {
    "name": "April Newsletter",
    "id": "5531",
    "template": {
      "name": "Newsletter A",
      "id": "8842"
    },
    "fromName": {
      "name": "EmailElement",
      "id": "61"
    },
    "subjectLine": {
      "name": "Your April update",
      "id": "733"
    }
  },
  "trackId1": "order-1001",
  "trackId2": "order-1002",
  "trackId3": "order-1003",
  "trackId4": "order-1004",
  "trackId5": "order-1005"
}
Something went wrong. Reloading the page usually fixes it. Reload ×

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.