Events reference
One full payload example for every webhook event — email, domain and account events.
Every event has this envelope. id is also the webhook-id header;
created_at is when the event happened. Receiving and verifying:
Webhooks.
{
"id": "evt_…",
"type": "email.delivered",
"created_at": "2026-11-16T09:00:02.400Z",
"data": { }
}Email events
Every email event's data has email_id, from, to, subject,
created_at (when the email was accepted) and tags.
One event per recipient. email.delivered, email.delivery_delayed,
email.bounced, email.complained and email.suppressed are about one
address, named in recipient (possibly a cc or bcc address). An email
to three people sends three email.delivered — or two, and one
email.bounced. email.sent, email.failed, email.expired and
email.canceled come once per email, with no recipient.
The email's own status, as GET /v1/emails/{id}
returns it, sums up its recipients: complained if any complained, else
bounced if any bounced, else delivered once every one was delivered, else
delivery_delayed if any is delayed, else sent.
Test-key emails and mail to the magic addresses send these
events too — simulated, same shape; a test key's carry "test": true in
data.
scheduled, queued and unknown have no event: the API's answer already
told you the first two, and unknown is not an ending (see
unknown).
email.sent
Our delivery infrastructure accepted the email and is handing it to the recipient's mail server.
{
"id": "evt_1a7k2m9x4q8w3n5p6r0s2t4v",
"type": "email.sent",
"created_at": "2026-11-16T09:00:00.910Z",
"data": {
"email_id": "em_8f2k1x9q4w7m3n5p6r0s2t4v",
"from": "Darin Game <orders@daringaming.com>",
"to": ["customer@example.com"],
"subject": "Your order #4821",
"created_at": "2026-11-16T09:00:00.120Z",
"tags": { "type": "order_confirmation" },
"test": false
}
}email.delivered
The recipient's mail server accepted the email. Inbox or spam is the receiving provider's decision.
{
"id": "evt_2b7k9x4m1q8w3n5p6r0s2t4v",
"type": "email.delivered",
"created_at": "2026-11-16T09:00:02.400Z",
"data": {
"email_id": "em_8f2k1x9q4w7m3n5p6r0s2t4v",
"from": "Darin Game <orders@daringaming.com>",
"to": ["customer@example.com"],
"subject": "Your order #4821",
"created_at": "2026-11-16T09:00:00.120Z",
"tags": { "type": "order_confirmation" },
"test": false,
"recipient": "customer@example.com"
}
}email.delivery_delayed
The receiving server is refusing for now (a full mailbox, a busy server). We
keep trying; email.delivered or email.bounced follows.
{
"id": "evt_3c8m1q4w7k2x3n5p6r0s2t4v",
"type": "email.delivery_delayed",
"created_at": "2026-11-16T09:05:00.000Z",
"data": {
"email_id": "em_8f2k1x9q4w7m3n5p6r0s2t4v",
"from": "Darin Game <orders@daringaming.com>",
"to": ["customer@example.com"],
"subject": "Your order #4821",
"created_at": "2026-11-16T09:00:00.120Z",
"tags": { "type": "order_confirmation" },
"test": false,
"recipient": "customer@example.com"
}
}email.bounced
The receiving server refused the email for this recipient. A permanent
bounce means the address doesn't exist: it is suppressed, and later emails
skip it. A transient one (a full mailbox, a message too large) is not
suppressed — the server kept refusing until we stopped retrying. sub_type
is one of general, no_email, suppressed,
on_account_suppression_list, mailbox_full, message_too_large,
content_rejected, attachment_rejected; message says it in words, and
diagnostic_code is the receiving server's own answer when it gave one.
{
"id": "evt_6m1q8w2b7k9x3n5p6r0s2t4v",
"type": "email.bounced",
"created_at": "2026-11-16T09:00:03.100Z",
"data": {
"email_id": "em_3n8v2c7x1k5d3n5p6r0s2t4v",
"from": "Darin Game <billing@daringaming.com>",
"to": ["old-address@example.com"],
"subject": "Your November invoice",
"created_at": "2026-11-16T09:00:00.500Z",
"tags": { "type": "invoice" },
"test": false,
"recipient": "old-address@example.com",
"bounce": {
"type": "permanent",
"sub_type": "no_email",
"message": "The recipient's mail server refused the email: the address does not exist.",
"diagnostic_code": "smtp; 550 5.1.1 user unknown"
}
}
}email.complained
The recipient marked the email as spam. The address is suppressed for the
API and for your Campaigns. It usually follows an email.delivered for the
same recipient, sometimes days later.
{
"id": "evt_4d9n2r5t8w1y3n5p6r0s2t4v",
"type": "email.complained",
"created_at": "2026-11-16T11:42:10.000Z",
"data": {
"email_id": "em_8f2k1x9q4w7m3n5p6r0s2t4v",
"from": "Darin Game <orders@daringaming.com>",
"to": ["customer@example.com"],
"subject": "Your order #4821",
"created_at": "2026-11-16T09:00:00.120Z",
"tags": { "type": "order_confirmation" },
"test": false,
"recipient": "customer@example.com"
}
}email.failed
The email couldn't be sent and won't be retried — for example, its domain
stopped verifying before a scheduled email's time came, or our delivery
infrastructure refused it (a virus in an attachment). failed.reason says
why in words. Refunded.
{
"id": "evt_5e1p3s6v9x2z3n5p6r0s2t4v",
"type": "email.failed",
"created_at": "2026-11-20T06:00:00.300Z",
"data": {
"email_id": "em_5k2m8x1q9w3r3n5p6r0s2t4v",
"from": "Clinic <bookings@clinic.example>",
"to": ["patient@example.com"],
"subject": "Reminder: your appointment tomorrow at 10:00",
"created_at": "2026-11-16T14:00:00.000Z",
"tags": { "type": "booking_reminder" },
"test": false,
"failed": { "reason": "clinic.example is no longer verified." }
}
}email.suppressed
This recipient is on your suppression list (an earlier hard bounce or spam
complaint), so it was skipped and not charged — one event per skipped
recipient. When every recipient was skipped, nothing is sent and the email's
status is suppressed.
{
"id": "evt_7g2r4v7y1b3d3n5p6r0s2t4v",
"type": "email.suppressed",
"created_at": "2026-11-16T09:10:00.050Z",
"data": {
"email_id": "em_9t3y6v1j407p3n5p6r0s2t4v",
"from": "Darin Game <orders@daringaming.com>",
"to": ["old-address@example.com"],
"subject": "Your order #4830",
"created_at": "2026-11-16T09:10:00.040Z",
"tags": { "type": "order_confirmation" },
"test": false,
"recipient": "old-address@example.com",
"suppressed": { "reason": "previous_bounce" }
}
}reason is previous_bounce or previous_complaint. Mail to
suppressed@sim.charchy.krd reads previous_bounce.
email.expired
Dropped because it couldn't leave in time: its expires_at passed, or it
waited 3 days past its due time while sending was paused. expired.reason
says which. Refunded.
{
"id": "evt_8h3s5v8z2c4f3n5p6r0s2t4v",
"type": "email.expired",
"created_at": "2026-11-16T12:10:00.000Z",
"data": {
"email_id": "em_2w5e8r1t4y7v3n5p6r0s2t4v",
"from": "My App <no-reply@myapp.example>",
"to": ["user@example.com"],
"subject": "Your sign-in code: 482910",
"created_at": "2026-11-16T12:00:00.000Z",
"tags": { "type": "signin_code" },
"test": false,
"expired": { "reason": "It could not leave before its expires_at, so it was dropped." }
}
}email.canceled
You canceled the email before it left. Refunded.
{
"id": "evt_9j4t6w9a3d5g3n5p6r0s2t4v",
"type": "email.canceled",
"created_at": "2026-11-17T08:30:00.000Z",
"data": {
"email_id": "em_5k2m8x1q9w3r3n5p6r0s2t4v",
"from": "Clinic <bookings@clinic.example>",
"to": ["patient@example.com"],
"subject": "Reminder: your appointment tomorrow at 10:00",
"created_at": "2026-11-16T14:00:00.000Z",
"tags": { "type": "booking_reminder" },
"test": false
}
}Domain events
domain.verified
The domain's DNS records checked out: you can send from any address on it now.
{
"id": "evt_0k5v7x1b4e6h3n5p6r0s2t4v",
"type": "domain.verified",
"created_at": "2026-11-16T08:12:00.000Z",
"data": { "domain": "daringaming.com" }
}domain.failed
Verification failed: the DKIM records weren't found within 72 hours, setup
failed, or a verified domain's records went missing at two daily re-checks a
few hours apart. Emails from it answer domain_not_verified. Check the
records on the Domains page; a domain whose records are put back sends
domain.verified again by itself
(if a domain stops verifying).
{
"id": "evt_116v8y2c5f7j3n5p6r0s2t4v",
"type": "domain.failed",
"created_at": "2026-11-19T03:00:00.000Z",
"data": { "domain": "daringaming.com" }
}Account events
account.paused
Sending is paused for your workspace — by our safety checks or our team.
New live requests answer sending_paused; accepted emails are held and go
out when sending resumes (unless their expires_at passes, or they wait
3 days — then they expire and are refunded). Test keys keep working. Your
owners and admins also get an email.
code is bounce_rate, complaint_rate, not_transactional,
provider_paused, reputation_finding or manual; reason says it in
words, with our numbers when we have them. volume_spike no longer pauses
sending (only events from before 2026-11-17 carry it).
{
"id": "evt_2m7w9z3d6g8k3n5p6r0s2t4v",
"type": "account.paused",
"created_at": "2026-11-18T15:00:00.000Z",
"data": {
"code": "bounce_rate",
"reason": "Too many of your recent emails bounced (hard bounces — addresses that do not exist). Sending to lists of addresses nobody gave you is the usual cause. Details: 4.20% hard bounces over the last 500 recipients"
}
}account.resumed
{
"id": "evt_3n8x1a4e7h913n5p6r0s2t4v",
"type": "account.resumed",
"created_at": "2026-11-19T10:00:00.000Z",
"data": {}
}balance.low
Your emails — this term's plan emails plus usable credits, as in the
x-charchy-emails-remaining header — are running out.
used_percent: 80— what is left fell to 20% of what you had after your last top-up.used_percent: 100— nothing is left. Live sends answer402 insufficient_balanceuntil you top up.
A top-up is a plan term starting (bought, renewed, or a paid-ahead term
taking over) or credits added. Each threshold fires once per top-up, from a
send; an ended term or expired credits don't fire it (you get emails about
those). emails_left is what's left now.
{
"id": "evt_4p9y2b5f8j1m3n5p6r0s2t4v",
"type": "balance.low",
"created_at": "2026-11-25T17:20:00.000Z",
"data": { "used_percent": 80, "emails_left": 2000 }
}Test events
Send test event in the dashboard sends any of these with "test": true
at the top level, next to id — to that endpoint only, whichever events it
subscribes to, even while it is failing.
data.test is different: on every email.* event, true when the email was
sent with a test key — the same as test on
GET /v1/emails/{id}. A sample from Send
test event has "test": true at the top and "test": false in data.