Webhook events
Every webhook payload has the same envelope. Only data changes between event types.
{
"id": "evt_01J8K2P...",
"type": "email.delivered",
"created_at": "2026-08-17T13:04:11Z",
"data": {
"email_id": "..."
}
}
id identifies the event, type says which one it is, and created_at is UTC.
What data carries depends on the family. email.* events carry email_id, so they tie back
to a message in Activity. email.received carries inbound_id
instead, because inbound mail is not a message you sent. domain.* and tracking_domain.*
carry domain_id. campaign.*, contact.* and suppression.* are workspace-wide and carry
neither.
Treat the type as an open list. New event types are added over time. Decode the envelope, match the types you handle, and ignore the rest rather than failing on an unfamiliar value.
Message delivery
| Type | Sent when |
|---|---|
email.sent | Handed off for outbound delivery |
email.delivered | The receiving server accepted the message; inbox placement is not confirmed |
email.bounced | The message failed for good: the receiving server rejected it, or it kept deferring it until attempts ran out. Sent once per failed message, not once per attempt |
email.opened | The tracking pixel loaded |
email.clicked | A tracked link in the message was followed |
email.complained | The recipient marked it as spam and their mailbox provider reported it |
email.failed | Sending ended in failure, including a permanent rejection, exhausted delivery attempts or a failure reported after delivery |
email.delayed | The receiving server asked for a later attempt. Sent for every attempt it puts off |
email.cancelled | The message was cancelled before it was sent |
Failures reported after delivery
email.bounced and email.failed can arrive after email.delivered. Some receiving servers
accept a message first and only later find they cannot deliver it, for example because the
mailbox behind a forwarding address no longer exists. They report that by sending a bounce
back to the message's bounce address, minutes or days afterwards.
When that report names a message you sent, Epostix records the bounce and sends
email.bounced. When the report came back to that message's own bounce address and clearly
names the failed recipient, the message's status also changes to failed and email.failed
follows. Otherwise you receive email.bounced only. A message that has
already been opened or clicked keeps its status, because a person evidently received it, and
produces email.bounced only.
Do not treat email.delivered as final. Let a later email.bounced or email.failed for the
same email_id override it.
Inbound mail
| Type | Sent when |
|---|---|
email.received | Mail arrived at one of your domains and the spam filter let it through |
email.return_path_reply | A person replied to the bounce address of a message you sent, rather than to its From or Reply-To |
email.received fires once, when the message arrives — not when you open it. Mail the filter
rejected, quarantined or discarded is stored but not announced, so a subscriber never acts on
a message Epostix already judged unwanted. See Inbound mail for the
verdicts.
email.return_path_reply covers the replies that email.received never sees. Some mail clients
answer the bounce address of a message instead of its From or Reply-To, and that address
belongs to Epostix, so the reply would otherwise be lost. It carries the email_id of the
message being answered, and a reply that produces it never also arrives as email.received.
Domains
| Type | Sent when |
|---|---|
domain.verified | A domain became verified: every required DNS record resolves |
domain.verification_failed | The records never resolved in time, or a verified domain stopped sending after its grace period |
domain.records_drifted | A required record of a verified domain stopped resolving; the domain is still sending |
tracking_domain.verified | A tracking domain's CNAME resolved |
tracking_domain.verification_failed | Epostix stopped checking a tracking domain |
These are the events to hang an onboarding flow off, because they say when a domain became able to send rather than when someone pressed a button.
Campaigns
| Type | Sent when |
|---|---|
campaign.started | A campaign began sending |
campaign.paused | Someone paused a campaign that was sending |
campaign.resumed | A paused campaign started sending again |
campaign.completed | Every message in the campaign has left the queue |
campaign.cancelled | A campaign was cancelled before it finished |
campaign.auto_paused | Epostix paused the campaign itself — its bounce or complaint rate tripped |
campaign.auto_paused is the one worth alerting on. It means sending stopped without anyone
asking, and its data carries the reason and the rates that tripped it.
Audience
| Type | Sent when |
|---|---|
contact.status_changed | A contact subscribed, unsubscribed, bounced or was cleaned |
contact.import_completed | A CSV import finished, successfully or not |
suppression.created | An address was added to the suppression list |
suppression.removed | An address was taken off the suppression list |
contact.status_changed is how an unsubscribe reaches your systems, including a one-click
unsubscribe from the mail client and a status change forced by a bounce.
webhook.test
webhook.test only ever arrives from Send a test event. It cannot be subscribed to. Its
data is a single message field, and it is delivered once with no retries.
What each one carries
Every email.* data object except email.received includes email_id and domain_id. The
fields below are what each type adds. A field with no value is left out rather than sent as
null or an empty string, so check for a key before you read it.
email.sent
email.delivered
{
"email_id": "...",
"domain_id": "...",
"attempt": 1,
"mx_hostname": "mx1.example.com",
"smtp_response": "250 2.0.0 OK"
}
attempt counts delivery attempts, starting at 1. mx_hostname is the receiving server that
accepted the message, and smtp_response is the line it accepted it with. Both depend on what
the receiving server reported, so either can be missing.
email.bounced
{
"email_id": "...",
"domain_id": "...",
"fault": "recipient",
"reason": "mailbox_unknown",
"permanent": true,
"source": "smtp",
"provider": "gmail",
"smtp_code": 550,
"enhanced_status_code": "5.1.1",
"response": "550 5.1.1 The email account that you tried to reach does not exist"
}
These are the verdict fields. The same set appears in the bounce object of email.failed
and email.delayed, in /events and in a suppression's bounce
history.
| Field | Meaning |
|---|---|
fault | Who the receiving server held responsible: recipient, sender or unknown. See who is at fault |
reason | Why it refused the message, such as mailbox_unknown or reputation. See reasons |
permanent | true when the receiving server said that retrying will not help |
source | smtp when the refusal was the server's reply during delivery, ndr when it came back later as a bounce message, suppression_list when the message was not sent because the address hard bounced on Epostix in the last 14 days |
provider | The mailbox provider, such as gmail, microsoft, yahoo or other |
smtp_code | The SMTP reply code, as a number. A bounce message that gave no code gets 550 or 450 from its status |
enhanced_status_code | The enhanced status code, such as 5.1.1 |
response | The receiving server's reply, as it wrote it |
to is the recipient address in lower case. provider, smtp_code, enhanced_status_code
and response are left out when the receiving server did not supply them.
email.bounced fires once per message, for a final refusal whatever its fault. Read fault
before you act on it: only a recipient fault says something about the address. A sender
fault says the receiving server refused the message or your sending reputation, and the same
address may accept your next message. A failure on the Epostix side never produces
email.bounced, because nothing about it is yours to fix.
A server that asks for a later attempt has not bounced the message. Each attempt it puts off
sends email.delayed. If attempts run out before it accepts the message, you receive one
email.bounced with the receiving server's last reply, usually with permanent set to
false, followed by email.failed. If no receiving server ever replied, for example because
the recipient's domain could not be reached, the message ends with email.failed only.
A bounce can also arrive after email.delivered; see
failures reported after delivery. See
bounce rate and suppression for what each one costs you, and
delivery events for how the classification is made.
email.complained
{
"email_id": "...",
"domain_id": "...",
"feedback_type": "abuse",
"provider": "microsoft",
"reported_at": "2026-08-17T13:04:11Z"
}
A complaint is not a rejection, so it carries none of the verdict fields.
feedback_type is the kind of report the provider sent: abuse for a spam click, or fraud,
virus or other. provider names the mailbox provider that
reported it, such as microsoft, yahoo or mailru. reported_at is when the provider says
the recipient reported the message, or when Epostix recorded the report if the provider
leaves that out. It can be days after delivery, so use it rather than the event's
created_at when you need to know when the complaint happened.
The event fires once per message and provider. Complaints only arrive from providers that run a feedback loop. Gmail does not report individual complaints, so a Gmail recipient marking your message as spam never produces this event.
By the time it arrives, Epostix has already suppressed the address. See complaints for what that blocks.
In test mode, [email protected] produces email.complained with
simulated and outcome added, and suppresses nothing.
email.failed
{
"email_id": "...",
"domain_id": "...",
"attempt": 1,
"reason": "550 5.1.1 The email account that you tried to reach does not exist",
"mx_hostname": "mx1.example.com",
"failure": {
"reason": "bounced",
"fault": "recipient"
},
"bounce": {
"fault": "recipient",
"reason": "mailbox_unknown",
"permanent": true,
"source": "smtp",
"provider": "gmail",
"smtp_code": 550,
"enhanced_status_code": "5.1.1",
"response": "550 5.1.1 The email account that you tried to reach does not exist"
}
}
email.failed fires once per message, when it has failed for good. It can follow a bounce, an
expired delivery attempt or a failure before the message was sent. The same message can emit
both email.bounced and email.failed.
failure says why the message failed, in values you can branch on. failure.reason names what
happened and failure.fault says who is responsible. The same object is on the message in
the API and on its failed event in
/events.
reason is a sentence for people to read: the receiving server's reply when there was one,
otherwise a fixed sentence from Epostix. Do not parse it. Branch on failure.reason instead.
failure.reason | What happened | failure.fault |
|---|---|---|
suppressed | The address is on your suppression list, so the message was not sent | recipient when the address bounced, complained or unsubscribed. sender when you suppressed it or cleaned it from an audience |
invalid_recipient | The address cannot receive mail, so the message was not sent | recipient |
bounced | The address refused the message: a receiving server rejected it, during delivery or afterwards, or the recipient's domain accepts no mail | recipient, sender or unknown, as in the bounce verdict |
expired | Receiving servers kept putting the message off until delivery attempts ran out | recipient, sender or unknown |
attachment_too_large | The attachments together exceed the size limit | sender |
attachment_unavailable | An attachment URL refused the request or points to an address Epostix will not fetch from, or an uploaded attachment had expired. A URL that is only temporarily unreachable is retried until the delivery window runs out | sender |
dkim_key_mismatch | The DKIM key published for the sending domain does not match the key it signs with, or no DKIM record is published for it. A missing record is retried until the delivery window runs out | sender |
sending_restricted | Sending from your workspace was restricted for longer than the message could wait. When its delivery window ran out, reason reads "The message could not be sent before its delivery window ran out" | sender |
platform_error | The failure was on the Epostix side. reason reads "The message could not be delivered" | Usually platform |
not_delivered | The message was not delivered, and the cause could not be attributed. When its delivery window ran out, reason reads "The message could not be sent before its delivery window ran out" | Usually unknown |
failure.fault | Meaning |
|---|---|
recipient | The cause is the address, not the message |
sender | The cause is the message, your sending domain or your workspace. The same address may accept a message once that is fixed |
platform | The cause was on the Epostix side. There is nothing for you to fix, and it never counts against your bounce rate |
unknown | Who is responsible could not be determined |
failure.fault and bounce.fault agree when both are present. Only failure.fault can be
platform, because a failure on the Epostix side is never a bounce.
Treat failure.reason as an open list. New values may be added. Handle the ones you act
on and fall back to failure.fault for the rest.
Messages that failed before Epostix began recording failure reasons have no failure. Their
events and API objects leave the field out, so check for it before you read it.
bounce carries the verdict fields and is there only when the failure is a
receiving server's refusal, during delivery or reported later. When the failure was on the
Epostix side, there is no bounce, failure.reason is platform_error and reason says
The message could not be delivered. A message that was never sent, for example because its
address is suppressed, carries only to, reason and failure. When delivery attempts run
out after a receiving server put the message off, bounce carries that server's last verdict
with permanent: false. When they run out without any reply from a receiving server, there is
no bounce.
email.failed can also arrive after email.delivered, when the receiving server reports the
failure later. reason is then what the receiving server said, or
The receiving server accepted the message and later reported that it could not be delivered
when it gave no detail. See
failures reported after delivery.
email.cancelled
{ "email_id": "...", "domain_id": "...", "to": "[email protected]", "reason": "cancelled_by_request" }
reason is cancelled_by_request when a scheduled send was cancelled,
workspace_suspended when the workspace was suspended before the message went out, and
The message could not be delivered when Epostix stopped a message that had already been
handed over for delivery.
email.delayed
{
"email_id": "...",
"domain_id": "...",
"attempt": 2,
"reason": "452 4.2.2 The recipient's mailbox is full",
"mx_hostname": "mx1.example.com",
"bounce": {
"fault": "recipient",
"reason": "mailbox_full",
"permanent": false,
"source": "smtp",
"smtp_code": 452,
"enhanced_status_code": "4.2.2",
"response": "452 4.2.2 The recipient's mailbox is full"
}
}
A delay is not a final failure and does not count as a bounce. When the receiving server put
the message off, bounce carries its verdict, with permanent normally false. When the
delay was on the Epostix side, there is no bounce and reason says Delivery is delayed.
When Epostix holds the message back itself, the event carries next_attempt_at instead, which
says when the next attempt is due. Follow the later delivery or failure event for the outcome.
email.opened
{
"email_id": "...",
"opened_at": "2026-08-17T13:04:11Z",
"is_machine_open": false,
"open_source": "..."
}
Check is_machine_open before you count an open. Apple privacy proxies and security
scanners fetch the tracking pixel without a person reading anything, and Epostix flags those
rather than dropping them so you can decide. Treating every email.opened as engagement will
overstate your open rate, in some audiences by a lot. See
how far to trust an open.
open_source names what Epostix thinks fetched the pixel, which is what makes a machine open
explainable rather than just excluded.
email.clicked
{
"email_id": "...",
"clicked_at": "2026-08-17T13:05:02Z",
"original_url": "https://...",
"is_machine_click": false
}
original_url is the destination as it was written in the message, before
link rewriting. is_machine_click is the same idea as
is_machine_open: scanners follow links to check them, and that is not a person clicking.
email.received
{
"inbound_id": "...",
"domain_id": "...",
"subject": "...",
"message_id": "...",
"spam_score": 0.4,
"spam_action": "no_action",
"size_bytes": 8421,
"attachment_count": 1,
"received_at": "2026-08-17T13:04:11Z"
}
There is no email_id: use inbound_id to fetch the message and its body.
email.return_path_reply
{
"email_id": "...",
"domain_id": "...",
"subject": "Re: ...",
"message_id": "...",
"received_at": "2026-08-17T13:04:11Z",
"text": "..."
}
email_id is the message being answered, so the reply ties back to it in
Activity. from is the address the reply came from, and received_at is when the reply reached Epostix. text is the reply's
plain-text content, or its HTML with the markup removed when it has no plain-text part, cut at
16 KiB. Nothing else from the reply is kept for you, so
store text if you need it: there is no inbound_id and no endpoint to fetch the reply later.
The event fires once per reply, and only when Epostix can tell which of your messages was answered. Automatic replies, such as out-of-office notices and challenge-response requests, never produce it.
domain.verified and domain.verification_failed
{
"domain_id": "...",
"domain": "yourdomain.com",
"status": "active",
"verified_count": 4,
"failed_count": 0,
"attempts": 3
}
Both fire only when the domain's status changes. The daily re-check of a domain that is already verified sends nothing, and neither do the hourly re-checks of a domain whose records have stopped resolving.
domain.records_drifted
{
"domain_id": "...",
"domain": "yourdomain.com",
"status": "active",
"kinds": ["dkim"],
"deadline_at": "2026-01-04T09:00:00Z"
}
Fires once, when a required record of a verified domain stops resolving. kinds lists the
records that failed. The domain keeps sending until deadline_at, 72 hours later. If the
records still fail then, sending stops and domain.verification_failed follows with
status: "deactivated". Records that resolve again before the deadline end the drift without
another event. A domain brought back after deactivation sends domain.verified.
The tracking-domain pair carries domain_id, hostname, verified, enabled, attempts
and last_verification_error instead of the domain.* payloads.
campaign.*
{
"campaign_id": "...",
"subject": "...",
"status": "completed",
"total_recipients": 12480
}
campaign.auto_paused adds reason and total_sent. reason is hard_bounce_rate,
spam_complaint_rate, bounce_spike or complaint_rate, and the rates that come with it depend
on what tripped:
{ "reason": "spam_complaint_rate", "hard_bounce_rate": 0.012, "spam_complaint_rate": 0.004, "total_sent": 1000 }
When recipients at one mailbox provider report the campaign as spam too often, the pause carries that provider's numbers instead:
{ "reason": "complaint_rate", "provider": "microsoft", "complaint_rate": 0.004, "complaints": 12, "total_sent": 3000 }
provider is microsoft, yahoo or mailru, the same values as in email.complained.
complaint_rate is a fraction (0.004 is 0.4%), complaints counts the recipients' reports and
total_sent counts the campaign's messages delivered to that provider. A complaint_rate pause
can also arrive with hard_bounce_rate and spam_complaint_rate instead, so check which fields
are present rather than assuming one shape.
contact.status_changed
reason is present only when the change carried one.
contact.import_completed
{
"job_id": "...",
"status": "completed",
"filename": "contacts.csv",
"total": 5000,
"processed": 4987,
"errors_count": 13
}
status is completed or failed, so check it rather than assuming the import worked.
suppression.created and suppression.removed
reason is manual for a list edit and names the cause when Epostix suppressed the address
itself. cleaned means Clean up found the address unusable. A
suppression with the reason complaint cannot be removed; see
complaints.
Narrowing an endpoint to a domain
An endpoint can be restricted to specific domains, so a workspace sending for several brands can route each one to its own handler. Leave it unset and the endpoint covers every domain, including domains you add later.
Only events that carry a domain can be narrowed — the email.*, domain.* and
tracking_domain.* families. campaign.*, contact.* and suppression.* are workspace-wide:
a campaign resolves its sending domain per batch rather than per campaign, and contacts and
suppressions are not tied to a domain at all. An endpoint subscribed to any of those has to
cover every domain, and the API refuses the combination rather than silently dropping events.
Choosing what to subscribe to
Every event you subscribe to is a request your server has to answer, and a failing endpoint is disabled after seven days regardless of which events caused it. Subscribing to everything on a high-volume workspace is the usual way to discover that your handler is slower than your send rate.
email.bounced and email.complained are the two worth having almost always, because both
change what you should do next. Opens and clicks are the highest volume by a wide margin, and
are the ones to leave off unless you are storing them. The domain, campaign and audience
families are low volume, so subscribing to them costs almost nothing.