---
title: "Email event webhooks"
description: "Signed POSTs to your https endpoint when mail arrives, goes out, bounces or is opened. Twenty events, retried for hours, ten endpoints per mailbox."
url: "https://openemail.uk/features/webhooks"
---

[Agents, API & MCP](https://openemail.uk/features.md#agents)

# 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.

[Open mail](https://openemail.uk/mail/inbox) [Get Started](https://openemail.uk/signup.md)[All features](https://openemail.uk/features.md)

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.

20

events to subscribe to

10

endpoints per mailbox

5

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 25 minutes, then 2 hours. Any other 4xx is final, and 410 switches the endpoint off.

## Twenty events in three families

Choosing none subscribes to every message event except email.replied.

email.received Arrived email.replied Reply arrived email.sent Accepted for sending email.delivered Receiver accepted email.delivery\_delayed Delayed, retrying email.failed Could not be sent email.bounced Came back email.complained Reported as spam email.suppressed Skipped, address suppressed email.scheduled Set for later email.queued Undo window running email.cancelled Taken back email.opened Opened email.clicked Link followed email.downloaded File fetched domain.verified Now receiving domain.sending\_changed Sending verdict moved domain.deleted Removed suppression.added Address added suppression.removed Address allowed again

## Verify a delivery

The SDK checks the HMAC in constant time and refuses deliveries over five minutes old.

Pass the raw body, not parsed JSON.

```
import { verifyWebhookSignature } from '@openemail/sdk' export default async (request: Request) => {  const event = await verifyWebhookSignature({    payload: await request.text(),    headers: request.headers,    secret: process.env.OPENEMAIL_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

1. 01
   
   Answer, then work
   
   Return a 2xx within five seconds and do slow work afterwards.
2. 02
   
   Drop repeated ids
   
   Store each X-OpenEmail-Delivery id you handle and skip repeats.
3. 03
   
   Rotate with both secrets
   
   Rotation replaces the secret at once, so verify against old and new until your deploy lands.

Questions

## Asked often

Keep going

## Works well with

REST API

A documented HTTP API with issuable, scopable, revocable keys.

Typed SDKs

A TypeScript client first, then the rest.

See when mail you sent was opened

Whether a message you sent has been opened, when, how many times and which of its links were followed. On unless you turn it off, and plain about the readings it cannot get.

Start

## Your domain, your mail.

Point a domain at OpenEmail and read it in a mailbox built around it. The free plan covers one domain.

[Open mail](https://openemail.uk/mail/inbox) [Get Started](https://openemail.uk/signup.md)[Read the reference](https://openemail.uk/docs/knowledge/agents/webhooks.md)