Webhooks
Told when it happens, not when you ask.
Register an https endpoint and get a signed POST when mail arrives, goes out, bounces or is opened.
In short
What is an email webhook?
A webhook is an HTTP request a service sends to your URL when something happens, so your code reacts instead of polling. For email, that means mail arriving, leaving, bouncing or being opened.
51
events to subscribe to
10
endpoints per mailbox
8
attempts per event at most
100
failed events in a row disable an endpoint
How it works
Every way of sending, one event
The composer, a send scheduled for Tuesday and the API all raise email.sent. Scheduling raises email.scheduled first.
Signed, and yours to check
Every POST carries an HMAC-SHA-256 of the timestamp and the raw body. Check the bytes as they arrived and refuse anything over 300 seconds old.
Retried only when it might work
Timeouts, 408, 425, 429 and 5xx are retried after 1, 5 and 30 minutes, then 2, 5, 10 and 10 hours. Any other 4xx is final, and 410 switches the endpoint off. Whatever still failed can be replayed, one event at a time, from the app or over the API.
51 events in 13 families
Choosing none subscribes to every message event except email.replied.
Verify a delivery
The SDK checks the HMAC in constant time and refuses deliveries over five minutes old.
import { verifyWebhookSignature } from '@nextmail/sdk' export default async (request: Request) => { const event = await verifyWebhookSignature({ payload: await request.text(), headers: request.headers, secret: process.env.NEXTMAIL_WEBHOOK_SECRET! }) console.log(event.type, event.data) return new Response(null, { status: 204 })}What you get
In the product today
Five seconds, in parallel
Endpoints are called at once, so ten still take five seconds.
Public https only
Private and loopback hosts are refused, and a redirect is never followed.
Every attempt logged
Each one shows what your server answered and how long it took.
Good practice
Getting the most out of it
- 01
Answer, then work
Return a 2xx within five seconds and do slow work afterwards.
- 02
Drop repeated ids
Store each X-OpenEmail-Delivery id you handle and skip repeats.
- 03
Rotate without a gap
After a rotation the old secret keeps signing for 24 hours, so deploy the new one within the day.
Questions
Asked often
Keep going
Works well with
Start
Your domain,
your mail.
Point a domain at Nextmail and read it in a mailbox built around it. The free plan covers one domain.
Google Workspace
Fastmail