Webhooks

Receive real-time notifications when email events occur.

Setup

Configure webhook endpoints in your dashboard. When an event occurs, we send a POST request to your endpoint with a JSON payload.

Event Types

deliveredEmail was successfully delivered to the recipient's mail server

bouncedEmail could not be delivered (hard or soft bounce)

openedRecipient opened the email (requires tracking pixel)

clickedRecipient clicked a tracked link in the email

complainedRecipient marked the email as spam

failedPermanent delivery failure after all retries

Payload Format

Each webhook delivery contains the following JSON payload:

{
  "id": "evt_abc123",
  "event": "delivered",
  "messageId": "em_xyz789",
  "timestamp": "2026-03-27T10:00:02Z",
  "metadata": {
    "to": "recipient@example.com",
    "subject": "Welcome aboard!",
    "ip": "203.0.113.42"
  }
}

Handling Webhooks

Your endpoint should return a 200 status within 5 seconds. Failed deliveries are retried up to 3 times with exponential backoff.

webhook-handler

app.post('/api/webhooks', (req, res) => {
  const { event, messageId, metadata } = req.body;

  switch (event) {
    case 'delivered':
      console.log(`Email ${messageId} delivered`);
      break;
    case 'bounced':
      console.log(`Email ${messageId} bounced`);
      // Remove from mailing list, notify team, etc.
      break;
    case 'opened':
      console.log(`Email ${messageId} opened`);
      break;
  }

  res.status(200).json({ received: true });
});

Retry Policy

Attempt	Delay	Timeout
1st	Immediate	5s
2nd	1 minute	5s
3rd	10 minutes	5s
4th (final)	1 hour	5s