Skip to main content

Webhooks

Webhooks notify your application when email events occur in real-time.

How Webhooks Work

1

Event Occurs

An email is sent, delivered, opened, etc.
2

Lettr Sends Webhook

A POST request is sent to your endpoint.
3

You Process

Your server processes the event and responds.

Create a Webhook

const webhook = await lettr.webhooks.create({
  url: 'https://example.com/webhooks/lettr',
  events: ['email.delivered', 'email.bounced', 'email.opened']
});

Webhook Payload

{
  "id": "evt_123abc",
  "type": "email.delivered",
  "createdAt": "2024-01-15T10:30:00Z",
  "data": {
    "emailId": "email_xyz",
    "to": "recipient@example.com",
    "subject": "Hello World",
    "deliveredAt": "2024-01-15T10:30:00Z",
    "metadata": {
      "orderId": "order_123"
    }
  }
}

Handle Webhooks

import express from 'express';
import { verifyWebhook } from 'lettr';

const app = express();

app.post('/webhooks/lettr', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['lettr-signature'];
  
  try {
    const event = verifyWebhook(req.body, signature, process.env.LETTR_WEBHOOK_SECRET);
    
    switch (event.type) {
      case 'email.delivered':
        console.log('Email delivered:', event.data.emailId);
        break;
      case 'email.bounced':
        console.log('Email bounced:', event.data.to);
        break;
      case 'email.opened':
        console.log('Email opened:', event.data.emailId);
        break;
    }
    
    res.sendStatus(200);
  } catch (err) {
    console.error('Webhook verification failed:', err.message);
    res.sendStatus(400);
  }
});

Available Events

EventDescription
email.sentEmail accepted by Lettr
email.deliveredEmail delivered to recipient
email.bouncedEmail bounced
email.openedRecipient opened the email
email.clickedRecipient clicked a link
email.complainedMarked as spam
email.unsubscribedRecipient unsubscribed

Testing Webhooks

Use the dashboard to send test events:
await lettr.webhooks.test('wh_123', {
  eventType: 'email.delivered'
});

Learn More