Email Webhooks

Overview

Register an HTTPS endpoint and we POST each email event to it as it happens, signed with a per-subscription secret. This is how you learn about a bounce or a spam complaint without polling the send log.

These webhooks are scoped to your own email events and are managed with the same cm_ key you send with. Up to 20 subscriptions per account.

Creating, updating and deleting need a write key. Listing and the delivery log are reads, so a read-only key works.

Create a subscription

POST /api/v1/email/webhooks

curl -X POST https://api.callmissed.com/api/v1/email/webhooks \
  -H "Authorization: Bearer cm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/email",
    "description": "Bounce + complaint handler",
    "events": ["email.bounced", "email.complained"]
  }'

The 201 response wraps the subscription and the secret:

{
  "webhook": {
    "id": "9d0f8b3a-1c2e-4a5b-8f7d-6e2a1b0c9d4e",
    "url": "https://your-app.com/hooks/email",
    "description": "Bounce + complaint handler",
    "events": ["email.bounced", "email.complained"],
    "secret_prefix": "whsec_A1b2C3",
    "is_active": true,
    "created_at": "2026-08-13T09:41:02.118Z"
  },
  "secret": "whsec_A1b2C3d4E5f6..."
}

The secret is returned once, here, and never again. Every later read exposes only secret_prefix. Store it when you create the subscription; if you lose it, delete the subscription and create a new one.

Events

You can subscribe to any of the six today. The four marked not emitted yet are accepted so your subscription does not have to be rewritten when they start firing — until then they simply deliver nothing. For inbound mail right now, use the per-address forward_url on Receive Email, which is live; for opens and clicks, read the aggregates from engagement metrics.

Payload

Every delivery is a POST with this envelope:

{
  "type": "email.bounced",
  "created_at": "2026-08-13T09:41:02.118431+00:00",
  "data": {
    "email_id": "9d0f8b3a-1c2e-4a5b-8f7d-6e2a1b0c9d4e",
    "message_id": "<1a2b3c4d@acme.com>",
    "recipient": "customer@example.com",
    "detail": "550 5.1.1 recipient address rejected",
    "domain": "acme.com"
  }
}

email.bounced and email.complained carry the shape above.

Headers

Content-Type: application/json
X-CallMissed-Signature: sha256=<hex digest>
X-CallMissed-Event: email.bounced
X-CallMissed-Delivery: 3f1c9a2d-4b5e-6a7f-8c9d-0e1f2a3b4c5d

X-CallMissed-Delivery is the delivery id, so a row in the delivery log can be matched to the request your handler saw. Use it to make your handler idempotent: a retried delivery reuses the same id.

Verifying the signature

The digest is HMAC-SHA256(secret, raw_request_body). Compute it over the raw bytes you received, before any JSON parsing, and compare with a constant-time function. Re-serialising the parsed JSON will not reproduce the signed bytes.

import hashlib, hmac

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", header)

There is deliberately no timestamp header: a timestamp the signature does not cover could be rewritten, so an age check based on it would not be trustworthy. Read created_at from the signed body instead.

Delivery behaviour

• Retries. A non-2xx response or a transport error is retried up to 3 attempts with exponential backoff. Anything in the 2xx range counts as success, so answer 200 as soon as you have accepted the event and do your work afterwards.
• Timeout. Each attempt allows 10 seconds for a response.
• Redirects are not followed. Point the subscription at its final URL.
• The URL is re-checked on every attempt. A URL that resolves to a private or internal address at send time is refused and the delivery is marked blocked rather than retried, even if it passed validation when you created the subscription.
• Events are not delayed by your endpoint. Delivery runs outside the request that produced the event, so a slow handler never slows a send or the processing of a bounce.
• Order is not guaranteed. Use created_at from the payload if you need to sequence events.

Delivery log

GET /api/v1/email/webhooks/deliveries returns every attempt chain, newest first, so you can tell "we never sent it" from "my handler returned 500".

# Everything, newest first
curl "https://api.callmissed.com/api/v1/email/webhooks/deliveries?limit=50&offset=0" \
  -H "Authorization: Bearer cm_your_key"

# Just one subscription
curl "https://api.callmissed.com/api/v1/email/webhooks/deliveries?webhook_id=9d0f8b3a-1c2e-4a5b-8f7d-6e2a1b0c9d4e" \
  -H "Authorization: Bearer cm_your_key"

Pause, resume and delete

PATCH /api/v1/email/webhooks/{id} takes one field, is_active (boolean), and returns the updated WebhookOut. This is how you stop a noisy endpoint without re-registering and redeploying a new secret.

# Stop deliveries, keep the URL, secret and history
curl -X PATCH https://api.callmissed.com/api/v1/email/webhooks/9d0f8b3a-1c2e-4a5b-8f7d-6e2a1b0c9d4e \
  -H "Authorization: Bearer cm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

# Resume
curl -X PATCH https://api.callmissed.com/api/v1/email/webhooks/9d0f8b3a-1c2e-4a5b-8f7d-6e2a1b0c9d4e \
  -H "Authorization: Bearer cm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'

# Remove it entirely
curl -X DELETE https://api.callmissed.com/api/v1/email/webhooks/9d0f8b3a-1c2e-4a5b-8f7d-6e2a1b0c9d4e \
  -H "Authorization: Bearer cm_your_key"

DELETE is a hard delete and also removes that subscription's delivery history, so a deleted subscription leaves none of your payloads behind. To stop deliveries while keeping the audit trail, PATCH is_active=false instead.

Common failures on these routes

The two reason bodies are nested under detail alongside an error string. Every shape is spelled out on Limits, Quotas & Errors.

Related

• Delivery, Suppressions & Usage for the send log, the suppression list and engagement metrics.
• Receive Email for inbound mail, which is forwarded per address rather than through this subsystem.
• Domains & Senders to turn open and click tracking on.