Zapmail
Overview
API Reference
Overview
API Reference
  1. Overview
  • Introduction
  • Quickstart
  • Authentication
  • MCP
  • Versioning
  • Errors
  • Webhooks
  • Rate Limits
  • Pagination
  • Changelog
  • Capabilities
    • Mailboxes
    • Pre-Warmed
    • Deliverability
    • Domains
    • Export to Sequencer
    • Zapbox
    • Team Management
    • ZapShield
    • ZapCare
    • AI Insight
    • Deliverability Tests
    • ZapSites
    • Zapwarm
    • ZapPulse
  • Billing
    • Understanding Zapmail billing
    • Wallet
  1. Overview

Webhooks

Webhooks push account events (domains, mailboxes, subscriptions, exports, Deliverability Tests, workspaces and email filters) to an HTTPS URL you control, so you do not have to poll the API. Zapmail signs every delivery, retries failures with backoff, and keeps a delivery log you can query and replay.
Before you start: you need an API key and a public HTTPS URL that returns a 2xx response within 10 seconds. All paths are under https://api.zapmail.ai/api/v3.
Webhook resources belong to the account of the API key. Events are emitted per account owner, so one endpoint receives events from every workspace of the account. There is no workspace filter on an endpoint; use the workspace ID in the payload to route events.

Set up an endpoint#

1
Create the endpoint
Call Create Webhook Endpoint with your url and the enabled_events you want. The endpoint starts active.
2
Store the secret
The response contains secret, a string starting with whsec_. It is returned only by this call. List and Get never include it, and it does not change when you update the endpoint. Store it in your secrets manager now. If you lose it, delete the endpoint and create a new one.
3
Verify the signature
Check X-Zapmail-Signature on every request. See Verify signatures.
4
Send a test event
Call POST /webhooks/endpoints/{id}/test to queue a test.ping event, then read the result with GET /webhooks/deliveries.

URL rules#

The URL must be valid. In production it must use HTTPS.
The host must resolve, and every address it resolves to must be public. Private, loopback, link-local and other reserved ranges are rejected.
The check runs when you create or update the endpoint and again immediately before every delivery attempt.
A URL that fails the check on create or update returns a 500 error with the message Internal server error, not a 4xx. Treat any 500 from these two calls as a URL problem first.
Redirects are not followed. Point the URL at the final location.

Endpoint management#

ActionRequest
List event typesList Webhook Event Types: GET /webhooks/events
CreateCreate Webhook Endpoint: POST /webhooks/endpoints
ListList Webhook Endpoints: GET /webhooks/endpoints (not paginated)
GetGET /webhooks/endpoints/{id}
UpdateUpdate Webhook Endpoint: PATCH /webhooks/endpoints/{id}
DeleteDELETE /webhooks/endpoints/{id}
Send a test eventPOST /webhooks/endpoints/{id}/test
List deliveriesGET /webhooks/deliveries
Resend a deliveryPOST /webhooks/deliveries/{id}/resend
PATCH accepts url, enabled_events and status (active or disabled). Send only what changes. enabled_events replaces the whole list and must contain at least one value. Setting status to active also resets the consecutive-failure counter.
Destructive. DELETE removes the endpoint and its secret, drops queued retries, and keeps the delivery history.
Fetch the event type catalogue with GET /webhooks/events instead of hardcoding it. test.ping is not in that list and cannot be subscribed to.

Event envelope#

Every delivery is an HTTP POST with a JSON body in this envelope.
FieldDescription
idEvent ID, evt_ followed by a UUIDv7. Generated once per event, not per attempt.
typeEvent type, for example mailbox.updated.
createdUnix timestamp in seconds when the event was generated.
api_versionEnvelope version, currently 2026-07-01.
dataHolds one key, object, with the event payload. Its shape depends on type.
{
  "id": "evt_0197d3a1-6c52-7f1e-9b0a-4a2d8c7e1b35",
  "type": "export.completed",
  "created": 1792999000,
  "api_version": "2026-07-01",
  "data": {
    "object": {
      "export_id": "9b1e6f3c-2d4a-4c8e-a7b5-1f0e3d6c8a92",
      "workspace_id": "a1b2c3d4-0000-0000-0000-000000000003",
      "app_name": "Instantly",
      "export_status": "COMPLETED",
      "mailboxes": [
        {
          "mailbox_id": "a1b2c3d4-0000-0000-0000-000000000002",
          "domain": "example.com",
          "username": "john",
          "first_name": "John",
          "last_name": "Doe"
        }
      ]
    }
  }
}
Request headers on every delivery:
HeaderValue
Content-Typeapplication/json
User-AgentZapmail-Webhooks/1.0
X-Zapmail-Signaturet=<unix seconds>,v1=<hex>

Event types#

TypeFires whendata.object
domain.updatedA domain's status, configuration or DNS state changes.domainDetails (allow-listed domain fields, including id, domain, status, workspaceId, serviceProvider, assignedMailboxesCount, health fields) and previousState (changed fields with their old values).
domain.connection_status_changedA step of the domain connection process completes or fails.id, domain, status, nameservers, expected_nameservers, next_retry_on, failure_reason.
mailbox.updatedA mailbox's status or configuration changes.mailboxDetails (allow-listed mailbox fields, including id, workspaceId, username, status, domain, serviceProvider, twoFactorEnabled; no password or secrets) and previousState.
subscription.status_changedA subscription's status changes.id, workspace_id, subscription_id, subscription_table, previous_status, status, subscription_type, billing_cycle, period_start, period_end.
subscription.billing_changedA subscription's billing details change.id, workspace_id, subscription_id, changes (each changed field as { previous, current }).
export.startedAn export job starts.export_id, workspace_id, app_name, export_status, mailboxes.
export.completedAn export job completes.Same as export.started, export_status COMPLETED.
export.failedAn export job fails.Same, export_status FAILED, plus error.
export.reconnectedAn export reconnects after a failure.Same, export_status RECONNECTED.
placement_test.status_changedA Deliverability Test's status changes.id, previous_status, status.
workspace.status_changedA workspace is archived, unarchived or deleted.id, name, previous_status, status.
workspace.invitationsA member accepts an invite, leaves, is removed, or has their role changed.workspace_id, action (invite_accepted, member_left, role_changed or member_removed), and, depending on the action, member_user_id, member_email, previous_role, new_role.
email.filter_matchedAn incoming email matches one of your email filter rules.filter_id, filter_name, filter_tag, workspace_id, account, service_provider, matched_criteria, applied_actions, email, matched_at.
test.pingYou call the test endpoint. Cannot be subscribed to.message: Test event from Zapmail.
Notes on specific payloads:
subscription.status_changed: subscription_table is one of USER, DNS_SHIELD, ZAP_CARE, PLACEMENT_TEST, AI_INSIGHT, PRE_WARMED_UP. workspace_id is null for subscriptions that are not tied to a workspace, such as ZapShield (DNS_SHIELD).
export.*: export_id is an internal export identifier. It is not the numeric exportId used by GET /exports/status, so you cannot correlate the two. Use workspace_id, app_name and the mailbox list to match an event to your request.
domain.updated and mailbox.updated: previousState contains only the fields that changed. serviceProvider is GOOGLE, MICROSOFT or null.
workspace.invitations: the action value determines which optional fields are present.
Example, domain.updated:
{
  "domainDetails": {
    "id": "a1b2c3d4-0000-0000-0000-000000000001",
    "workspaceId": "a1b2c3d4-0000-0000-0000-000000000003",
    "domain": "example.com",
    "status": "CONNECTED",
    "serviceProvider": "GOOGLE",
    "healthScore": 92,
    "healthLabel": "Healthy",
    "assignedMailboxesCount": 5
  },
  "previousState": { "status": "PENDING" }
}
Example, domain.connection_status_changed:
{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "domain": "example.com",
  "status": "NS_NOT_CHANGED",
  "nameservers": ["ns1.registrar.com", "ns2.registrar.com"],
  "expected_nameservers": ["ns1.zapmail.com", "ns2.zapmail.com"],
  "next_retry_on": "2026-10-27T12:00:00.000Z",
  "failure_reason": "Ensure your Zapmail NS records are updated at your domain registrar."
}
The payloads above show representative fields. Treat unknown fields as additive and ignore them.

Verify signatures#

Every delivery carries this header:
X-Zapmail-Signature: t=1792999000,v1=5257a869e7bfbe86...
t is the Unix time in seconds when the attempt was signed. It is regenerated on every attempt, so retries and resends carry a fresh t.
v1 is the hex-encoded HMAC-SHA256 of the string <t>.<raw request body>, keyed with the endpoint secret (the whole whsec_... string).
To verify:
1.
Read the raw request body bytes before any JSON parsing.
2.
Split the header into t and v1.
3.
Compute HMAC-SHA256 of t, a dot, and the raw body, using the secret as the key, and hex-encode it.
4.
Compare it to v1 with a constant-time comparison.
5.
Check that t is close to the current time.
Use the raw body
Re-serialising parsed JSON can change whitespace or key order and break the signature. In Express, use express.raw({ type: 'application/json' }) for the webhook route.
Recommendation: replay protection
Zapmail does not enforce a timestamp window on your side. We recommend rejecting requests whose t differs from your clock by more than 5 minutes (300 seconds), and de-duplicating on the envelope id. This is a recommendation, not a requirement.
Node.js
Python

Delivery and retries#

A delivery succeeds on any 2xx response within 10 seconds. A non-2xx response, a timeout, a network error or a redirect is a failed attempt.
Delivery is at-least-once. De-duplicate on the envelope id.
A failed delivery is retried up to 7 more times, after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 24 hours. That is 8 attempts in total.
After 20 consecutive deliveries exhaust all their attempts, the endpoint is set to disabled and the account owner is emailed. Any successful attempt resets the counter. Test events never count toward it.
A disabled endpoint receives nothing. Re-enable it with PATCH /webhooks/endpoints/{id} and { "status": "active" }.

Inspect and replay deliveries#

GET /webhooks/deliveries lists deliveries newest first, one row per event and endpoint, showing the most recent attempt. Filter with endpoint_id, status (succeeded or failed) and event_type, and page with page and limit. The response is { deliveries, total }.
Each row includes the exact payload that was sent, attempt_number, response_code, error and the first 10,000 characters of your response_body. The row id identifies the latest attempt. test.ping deliveries are listed but cannot be selected with event_type.
POST /webhooks/deliveries/{id}/resend queues another attempt of an earlier event to the same endpoint with the original payload (same event id) and a new signature timestamp. The call returns once the attempt is queued, and the result appears as the next attempt_number. If the endpoint is disabled, the attempt is queued but never sent. If the endpoint was deleted, the call returns 404.

Consumer checklist#

Verify the signature on the raw body before parsing.
Return a 2xx quickly. Queue the work and process it asynchronously, because slow handlers count against the 10-second timeout.
Store the raw payload and the event id before processing, and ignore event IDs you have already handled.
Subscribe only to the events you use.
Monitor for disabled status on your endpoints.
Related: Create Webhook Endpoint, List Webhook Event Types, Authentication, Errors.
Previous
Errors
Next
Rate Limits
Built with