.agents/skills/email-best-practices/resources/webhooks-events.md
Receiving and processing email delivery events in real-time.
| Event | When Fired | Use For |
|---|---|---|
email.sent | Email accepted by Resend | Confirming send initiated |
email.delivered | Email delivered to recipient server | Confirming delivery |
email.bounced | Email bounced (hard or soft) | List hygiene, alerting |
email.complained | Recipient marked as spam | Immediate unsubscribe |
email.opened | Recipient opened email | Engagement tracking |
email.clicked | Recipient clicked link | Engagement tracking |
Your endpoint must:
app.post('/webhooks/resend', async (req, res) => {
// Return 200 immediately to acknowledge receipt
res.status(200).send('OK');
// Process asynchronously
processWebhookAsync(req.body).catch(console.error);
});
Always verify webhook signatures to prevent spoofing.
import { Webhook } from 'svix';
const webhook = new Webhook(process.env.RESEND_WEBHOOK_SECRET);
app.post('/webhooks/resend', (req, res) => {
try {
const payload = webhook.verify(
JSON.stringify(req.body),
{
'svix-id': req.headers['svix-id'],
'svix-timestamp': req.headers['svix-timestamp'],
'svix-signature': req.headers['svix-signature'],
}
);
// Process verified payload
} catch (err) {
return res.status(400).send('Invalid signature');
}
});
Configure your webhook endpoint in the Resend dashboard or via API.
async function handleBounce(event) {
const { email_id, email, bounce_type } = event.data;
if (bounce_type === 'hard') {
// Permanent failure - remove from all lists
await suppressEmail(email, 'hard_bounce');
await removeFromAllLists(email);
} else {
// Soft bounce - track and remove after threshold
await incrementSoftBounce(email);
const count = await getSoftBounceCount(email);
if (count >= 3) {
await suppressEmail(email, 'soft_bounce_limit');
}
}
}
async function handleComplaint(event) {
const { email } = event.data;
// Immediate suppression - no exceptions
await suppressEmail(email, 'complaint');
await removeFromAllLists(email);
await logComplaint(event); // For analysis
}
async function handleDelivered(event) {
const { email_id } = event.data;
await updateEmailStatus(email_id, 'delivered');
}
Webhooks may be sent multiple times. Use event IDs to prevent duplicate processing.
async function processWebhook(event) {
const eventId = event.id;
// Check if already processed
if (await isEventProcessed(eventId)) {
return; // Skip duplicate
}
// Process event
await handleEvent(event);
// Mark as processed
await markEventProcessed(eventId);
}
If your endpoint returns non-2xx, webhooks will retry with exponential backoff:
Local development: Use ngrok or similar to expose localhost.
ngrok http 3000
# Use the ngrok URL as your webhook endpoint
Verify handling: Send test events through Resend dashboard or manually trigger each event type.