Email Webhooks

Webhooks let Routee push delivery and engagement events to your application in real time — no polling required. For transactional email, webhooks are configured per message using the callback object on the send request.

📘

Prefer to pull instead of push?

You can also query the Tracking API (GET /email/tracking/single/{trackingId}) at any time. Webhooks and the Tracking API report the same events.

Configure callbacks on send

Add a callback object to your POST https://connect.routee.net/transactional-email payload. Routee then POSTs JSON to your HTTPS endpoints as the message progresses.

curl -X POST 'https://connect.routee.net/transactional-email' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": { "address": "[email protected]" },
    "to":   [{ "address": "[email protected]" }],
    "subject": "Password reset",
    "content": { "html": "<p>Reset your password.</p>" },
    "callback": {
      "statusCallback": {
        "strategy": "OnChange",
        "url": "https://your-app.example/webhooks/email-status?token=YOUR_SECRET"
      },
      "eventCallback": {
        "onOpen":  "https://your-app.example/webhooks/email-open?token=YOUR_SECRET",
        "onClick": "https://your-app.example/webhooks/email-click?token=YOUR_SECRET"
      }
    }
  }'

Callback types

📘

Webhooks vs skip tracking

eventCallback only configures where to POST open/click events. Click rewriting and the open pixel are on by default (trackLinks / trackOpens). Set them to false on the send body to skip instrumentation. See Track Links & Opens Explained.

Callback strategies

Delivery status values

Status callbacks carry the same lifecycle values as the tracking timeline:

A human-readable status accompanies the machine deliveryStatus. Each notification also identifies the message by its trackingId (the id returned by the send request).

DELIVERED, BOUNCED, and FAILED are final. Routee does not send a later QUEUED callback for the same message.

Handling webhooks reliably

• Respond fast: return 2xx immediately, then process asynchronously (queue the payload). Slow endpoints may be retried or timed out.
• Be idempotent: the same event can be delivered more than once (retries). De-duplicate on trackingId + status + timestamp before acting. After BOUNCED or FAILED, there is no later QUEUED for that message.
• Secure the endpoint: serve over HTTPS and include a hard-to-guess secret in the callback URL (path segment or query string) that you validate on every request. Reject anything without it. Restrict by source IP where possible.
• Expect ordering gaps: events can arrive out of order (e.g. an open before the delivered status). Rely on timestamp, not arrival order.

👍

Step-by-step

See the tutorial Receive transactional email delivery callbacks for an end-to-end receiver.

Next steps

• Email tracking, statuses & callbacks — full status list and the pull-based Tracking API
• Send a transactional email — the callback object reference
• Callback Object Explained · Status Callback Object Explained · Track Links & Opens Explained

Callback retry policy

Your endpoint must respond with HTTP 200 OK within 2 seconds. Otherwise Routee closes the connection and retries (up to 12 attempts over 24 hours).

Design your handler to be idempotent — the same event may be delivered more than once.