POST each time something you care about happens. That can be an email event (a delivery, a bounce, an open, or a click) or a lifecycle change to one of your sending domains or webhook endpoints. You subscribe a URL to a set of events and mailkube pushes them to you as they occur.
Webhooks are managed in the dashboard by organization owners, admins, and members. The billing role has no access.
How a delivery reaches you
Three properties of that flow decide how you build the receiver.- Each event type reaches one endpoint per domain. Subscriptions cannot overlap. Moving an event to a second endpoint takes it off the first, with no redelivery of anything already in flight.
- The
POSTis a request you answer within 10 seconds. Acknowledge first and queue the work. A handler that does its own database writes inline is the usual cause of a retry storm. - The response status is the only signal mailkube reads. It does not parse your body and it does not follow a redirect.
Adding an endpoint
Before mailkube saves an endpoint, it verifies that you control the URL you entered. Your server answers a one-time challenge before you submit. The listener has to be running and publicly reachable before you submit the form. The challenge is sent during creation, not after it.1
Answer the verification challenge
When you add an endpoint, mailkube sends a single Your server must reply If the challenge isn’t echoed (wrong body, a non-200 status, a redirect, a TLS error, or a timeout), the endpoint is not created.
GET to your URL:200 OK with a body equal to the token, within 5 seconds. There is no shared verify token; echoing the challenge is the proof.2
Choose what to send
email.bounced fires only on a permanent failure (the address is dead). A
temporary problem, a deferral or a message that ran out of retries,
arrives as email.delivery_delayed instead, so a later attempt may still
deliver.email.suppressed fires when a recipient is filtered from a send. Two things
suppress an address: it previously hard-bounced (scoped to your sending
domain’s apex: a bounce on mail.acme.com also suppresses news.acme.com), or
it unsubscribed from an opt-out topic this send was attributed
to. The send is accepted and counts against your quota, but the message is
dropped before delivery. It produces no email.delivered and no
email.bounced. data.suppression.recipients lists the suppressed addresses;
remove them from your own lists to stop paying for sends that can never deliver.Verifying signatures
Every delivery is signed with your endpoint’s signing secret so you can confirm it really came from mailkube. EachPOST carries three headers:
The signature is computed over the delivery id, the timestamp, and the exact raw body, joined with dots. This is the wire contract. Reach for it if you are on a language with no mailkube SDK:
X-Webhook-Ts has aged past a 300-second window, and returns a typed event.
On a supported framework, the integration package carries the whole receiver: it verifies the raw body, answers the delivery, and hands your code a typed event through the framework’s own dispatch mechanism.
An event type your installed version does not model still reaches your handler with its payload intact. A new platform event never breaks a running receiver.
Receiving them from the terminal
The CLI runs a verified receiver on your machine, which covers local development and CI without a deployed endpoint:listen answers the registration challenge itself, so start it before you add the endpoint in the dashboard. Its --filter, --exit-after and --exit-timeout flags turn the listener into an assertion a CI job can make about a send.
For local development. Start from webhook-inspector, a boilerplate receiver that answers the verification challenge and prints the events it receives. It verifies signatures with the official
mailkube Python SDK (verify_signature / parse_event). It opens a Cloudflare Tunnel (cloudflared) to expose your local server at a public https:// URL you can add to mailkube. It’s meant for development and testing; it is not production-grade.Signing, for your tests
Production code verifies; it never signs. But to exercise your handler without waiting on a real delivery, each SDK exposes the signing half too,sign in Python and Node, Webhooks.sign in Ruby, PHP and Java, and mailkube.Sign in Go:
sign computes the HMAC exactly as verify checks it, so a fixture built this way can’t drift from the verifier the way a hand-rolled one eventually does. It takes the timestamp you give it and doesn’t judge its freshness. Pass a stale one to confirm your handler rejects a replay.
Email events
Every email event shares a common envelope of atype, a created_at, and a data block whose message context (email_id, from, to, subject, domain, and any tags you attached to the send) identifies the message. Each event adds one nested object with its specifics. All timestamps are ISO-8601 UTC: the envelope’s created_at spells the offset as +00:00, while the timestamps inside data use the Z form; both carry fractional seconds when the instant has them. (The email.suppressed payload is shown above; its data follows the same shape with a suppression block.)
The email_id is the same UUID across every event for one message. It threads the whole lifecycle, from email.scheduled (if it was scheduled) through email.sent (accepted for delivery) to email.delivered, email.bounced, or email.failed.
A receiving server can accept a message and report a delivery failure later. Your endpoint then gets an email.bounced, or an email.delivery_delayed for a temporary failure, after the email.delivered for the same email_id.
email.scheduled
The send was accepted for later transmission, and a scheduled email was created. Fires at schedule time, once quota is charged and the body is rendered. scheduled.batch_id is null when the send wasn’t grouped into a batch.
email.sent
The message was accepted and spooled by the mail transfer agent, the handoff moment before any delivery outcome. It precedes any email.delivered or email.bounced for the same email_id, and carries no SMTP response, so sent is a recipient plus a timestamp.
email.delivered
The message was accepted by the recipient’s mail server.
email.bounced
A permanent failure. The address is dead, and code and reason carry the receiving server’s response.
email.delivery_delayed
A temporary problem, a deferral or a message that ran out of retries. A later attempt may still deliver. Same shape as a bounce, under a delay key.
email.opened
The recipient opened the message. This example shows the default: the sending domain has not
enabled either connection-data setting, so the open block carries only a timestamp. See
Recipient connection data.
email.clicked
The recipient clicked a tracked link. link is the clicked URL. This example shows a domain that
has enabled both connection-data settings; see Recipient connection data.
Recipient connection data
ipAddress, country and userAgent are the only keys in any payload whose presence depends on
your configuration. Two per-domain settings control them, both off by default:
Both are on the domain’s settings page in the dashboard, below the click and open tracking toggles.
Three things to know before you turn them on:
- A key you have not enabled is absent, not
nulland not"". Your handler can tell “not recorded” from “recorded blank”. Each SDK surfaces that absence in its own idiom, an optional type or a zero value. countrycan be absent even whenipAddressis present. It is resolved at the edge and is not available on every path, so treat it as optional too.- Recording this data can require your recipient’s consent, depending on where they are. You are the controller of that decision and responsible for having any permission the law requires; mailkube records the fields on your instruction and uses them for nothing of its own.
email.failed
A scheduled email the platform had already accepted was terminally dropped at send time. Without this event, an email you scheduled 30 days out could be dropped silently; subscribe to it to catch that. It shares the email_id of the earlier email.scheduled, and is distinct from email.suppressed (which fires at the normal send-path gate): email.failed marks a send the platform had already accepted for later.
failed.reason is a stable code, never a raw transport string, one of:
Lifecycle events
Beyond per-message email events, two events tell you when your resources change state. Your integration never polls for them.domain.status
Fires whenever one of your sending domains changes status or onboarding_state, as it progresses through onboarding, is suspended (on_hold) for reputation or as part of an apex-wide suspension, has that suspension lifted, or is deleted. The payload carries the new state plus a previous block so you can diff the transition:
webhook.status
Fires whenever one of your webhook endpoints changes state: you disable or re-enable it, mailkube auto-disables it for low quality, or it is deleted. disabled_reason distinguishes a manual (user) disable from an automatic (low_quality) one.
Because each event goes to one endpoint per domain, a
webhook.status event about an endpoint is delivered to whichever endpoint subscribes to webhook.status, and never to an endpoint that is being disabled or deleted (only active endpoints receive deliveries). Point webhook.status at a separate, always-on endpoint if you want to observe these changes reliably.Delivery and retries
A delivery is an HTTPSPOST with the signed payload. Your server has 10 seconds to answer with a success status; hand slow work to a queue and return early. Redirects are never followed, on the verification challenge or on deliveries. The endpoint URL must answer directly.
A failed attempt is retried with exponential backoff. The first retry waits two minutes, each following wait doubles, and the wait stops growing at 48 hours. mailkube makes 15 attempts in total, then abandons the delivery. X-Webhook-Id stays stable across every one of them, so deduplicate on it. A payload over 64 KB cannot be delivered and is dropped rather than retried.
Anything outside 2xx is a failed attempt, a 3xx included: an endpoint that redirects spends its attempt budget on redirects. Connection failures, TLS errors and timeouts count the same way.
Editing an endpoint
Open an endpoint in the dashboard to change it:- Endpoint URL. Moving to a new URL re-runs the verification challenge above.
- Events. Adjust which events you receive at any time.
- Active. Turn an endpoint off to pause delivery without losing it, and back on to resume. An endpoint that keeps failing may also be disabled automatically; see Endpoint health and automatic disabling.
Endpoint health and automatic disabling
Each endpoint carries a first-attempt acceptance rate: how often your server returns a success status on the first delivery attempt, measured over a rolling window. A failed delivery is still retried with backoff; the rate measures how healthy the endpoint is overall. An endpoint whose rate stays low, once it has carried enough recent traffic to judge, is disabled automatically so it stops spending your retry budget on a target that isn’t accepting events. When that happens:- The endpoint appears in your list as disabled with a “Low quality” reason, distinct from one you turned off yourself.
- Anyone subscribed to the Webhook health alerts email topic for your organization is notified, with the endpoint URL and the acceptance rate that triggered it.
An endpoint records why it is disabled (by you, or by mailkube for low quality)
and, for an automatic disable, its quality score: the first-attempt
acceptance rate (
0 to 1) captured at the moment it was disabled. A healthy
endpoint carries no score.Rotating the signing secret
If your signing secret is lost or exposed, you can roll it from the endpoint’s menu in the dashboard. Rolling generates a fresh secret and shows it once, exactly like creation. The endpoint, its URL, and its event subscriptions are unchanged; only the secret changes, so there is no new verification challenge. Rolling is rate-limited per endpoint.Related
- Domains. An endpoint subscribes to events from one active domain.
- Quickstart. Send the emails whose events you’ll receive.
- Receiving webhooks with the CLI. Run a verified receiver locally, replay a capture, and assert delivery in CI.
- SDKs. Every SDK verifies a delivery, and the four framework packages carry the whole receiver.