Webhooks
Email Delivery Events
Receive real-time notifications about email delivery status. Configure your webhook URL in the dashboard. All events are signed with HMAC-SHA256 for security.
https://your-server.com/webhook/email/deliveryAlways verify the webhook signature. Generate your webhook secret in the dashboard and use it to verify incoming requests. Compute the HMAC over the raw request body, not over re-serialized JSON.
Quick start
A listener that verifies the signature and then handles the event. Reply with a 2xx status once the event is accepted.
const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
function verifySignature(rawBody, signature) {
if (!signature) return false;
const expected = 'sha256=' + crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(rawBody)
.digest('hex');
const a = Buffer.from(signature);
const b = Buffer.from(expected);
// timingSafeEqual throws when the lengths differ
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// express.raw keeps the body as a Buffer, exactly as it was sent
app.post('/webhook/email/delivery', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifySignature(req.body, req.headers['x-webhook-signature'])) {
return res.status(401).json({ error: 'Invalid signature' });
}
const { event, emailId, data } = JSON.parse(req.body.toString('utf8'));
console.log('[Email Delivery] ' + event + ' - ' + emailId);
if (event === 'delivered') {
console.log(' Recipient: ' + data.recipientEmail);
} else if (event === 'bounced') {
console.log(' Reason: ' + data.reason);
}
res.status(200).json({ received: true });
});
app.listen(3001, () => {
console.log('Email delivery webhook listener on port 3001');
console.log(' POST /webhook/email/delivery');
});Headers
X-Webhook-SignaturestringrequiredHMAC-SHA256 signature of the request body. Format:
sha256=hex_digest
Testing with ngrok
Expose your local listener to the internet and register the generated URL as your webhook URL in the dashboard.
ngrok http 3001
# Your webhook URL:
# https://abc123.ngrok.io/webhook/email/deliveryEvents
Every event is a JSON object with event, timestamp and a data object. Open an event for its full payload and fields.
Delivery
What happens to an email on its way to the inbox.
queuedSent once when an email enters the delivery queue, for every email: API, SMTP and campaigns. Sent again when the email is moved to another IP or server to be tried again.
processingSent when the email passed our checks and is about to be sent to the receiving server.
deliveredSent when the receiving mail server accepts the email.
bouncedSent when an email is rejected for good: the address does not exist, the domain cannot receive mail, or we stopped trying.
spamSent when the receiving mail server refuses the email as spam or for a policy reason while we deliver it.
retryingSent each time an email could not be delivered yet and will be tried again.
failedSent when we give up on an email after its retries run out.
return_pathSent when a bounce message (DSN) arrives later, after the receiving server had first accepted the email. A failure moves the email to bounced. A delay or delivery notice only sends this event.
Tracking
What the recipient does after it arrives.
email_openedSent when a recipient opens an email with open tracking on. Includes the device, IP, country and whether the open came through a proxy.
email_clickedSent when a recipient clicks a link in an email with click tracking on. Includes the URL and whether it was the first click.
unsubscribeSent when a recipient unsubscribes from one of your emails: on the unsubscribe page, with the one-click button of their mailbox (Gmail, Yahoo, Outlook) or by email through the List-Unsubscribe header.
tracking_preferences_updatedSent when a recipient changes their open or click tracking choice on the tracking preferences page. They keep receiving your emails: this is not an unsubscribe.
Your endpoint failing too often? See List Webhooks to check its status, or Retry All Failed to requeue what was missed.