Skip to main content

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.

note

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​

TypeSent when
email.sentHanded off for outbound delivery
email.deliveredThe receiving server accepted the message; inbox placement is not confirmed
email.bouncedThe 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.openedThe tracking pixel loaded
email.clickedA tracked link in the message was followed
email.complainedThe recipient marked it as spam and their mailbox provider reported it
email.failedSending ended in failure, including a permanent rejection, exhausted delivery attempts or a failure reported after delivery
email.delayedThe receiving server asked for a later attempt. Sent for every attempt it puts off
email.cancelledThe 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​

TypeSent when
email.receivedMail arrived at one of your domains and the spam filter let it through
email.return_path_replyA 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​

TypeSent when
domain.verifiedA domain became verified: every required DNS record resolves
domain.verification_failedThe records never resolved in time, or a verified domain stopped sending after its grace period
domain.records_driftedA required record of a verified domain stopped resolving; the domain is still sending
tracking_domain.verifiedA tracking domain's CNAME resolved
tracking_domain.verification_failedEpostix 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​

TypeSent when
campaign.startedA campaign began sending
campaign.pausedSomeone paused a campaign that was sending
campaign.resumedA paused campaign started sending again
campaign.completedEvery message in the campaign has left the queue
campaign.cancelledA campaign was cancelled before it finished
campaign.auto_pausedEpostix 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​

TypeSent when
contact.status_changedA contact subscribed, unsubscribed, bounced or was cleaned
contact.import_completedA CSV import finished, successfully or not
suppression.createdAn address was added to the suppression list
suppression.removedAn 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_id": "...", "domain_id": "...", "to": "[email protected]" }

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.

FieldMeaning
faultWho the receiving server held responsible: recipient, sender or unknown. See who is at fault
reasonWhy it refused the message, such as mailbox_unknown or reputation. See reasons
permanenttrue when the receiving server said that retrying will not help
sourcesmtp 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
providerThe mailbox provider, such as gmail, microsoft, yahoo or other
smtp_codeThe SMTP reply code, as a number. A bounce message that gave no code gets 550 or 450 from its status
enhanced_status_codeThe enhanced status code, such as 5.1.1
responseThe 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.reasonWhat happenedfailure.fault
suppressedThe address is on your suppression list, so the message was not sentrecipient when the address bounced, complained or unsubscribed. sender when you suppressed it or cleaned it from an audience
invalid_recipientThe address cannot receive mail, so the message was not sentrecipient
bouncedThe address refused the message: a receiving server rejected it, during delivery or afterwards, or the recipient's domain accepts no mailrecipient, sender or unknown, as in the bounce verdict
expiredReceiving servers kept putting the message off until delivery attempts ran outrecipient, sender or unknown
attachment_too_largeThe attachments together exceed the size limitsender
attachment_unavailableAn 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 outsender
dkim_key_mismatchThe 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 outsender
sending_restrictedSending 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_errorThe failure was on the Epostix side. reason reads "The message could not be delivered"Usually platform
not_deliveredThe 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.faultMeaning
recipientThe cause is the address, not the message
senderThe cause is the message, your sending domain or your workspace. The same address may accept a message once that is fixed
platformThe cause was on the Epostix side. There is nothing for you to fix, and it never counts against your bounce rate
unknownWho 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.

note

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": "..."
}
warning

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": "...",
"from": "[email protected]",
"to": ["[email protected]"],
"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": "...",
"from": "[email protected]",
"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": "...",
"from_email": "[email protected]",
"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​

{ "contact_id": "...", "email": "[email protected]", "status": "unsubscribed", "reason": "..." }

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​

{ "email": "[email protected]", "reason": "hard_bounce" }

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.