Charchy Senddocs

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 answer 402 insufficient_balance until 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.

On this page