Webhooks

RustMail can POST a JSON notification to an HTTP endpoint whenever a new email is received.

Setup

rustmail serve --webhook-url https://hooks.example.com/email

Or via environment variable:

RUSTMAIL_WEBHOOK_URL=https://hooks.example.com/email rustmail serve

Or in rustmail.toml:

webhook_url = "https://hooks.example.com/email"

Payload

Each webhook is an HTTP POST with Content-Type: application/json. The body is a message summary:

{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "sender": "user@example.com",
  "recipients": ["recipient@example.com"],
  "subject": "Hello World",
  "size": 1024,
  "has_attachments": false,
  "is_read": false,
  "is_starred": false,
  "tags": [],
  "created_at": "2026-03-23T10:30:45Z"
}

Field	Type	Description
id	string	ULID: use this to fetch the full message via the REST API
sender	string	Envelope sender address
recipients	array of strings	Envelope recipient addresses
subject	string | null	Parsed subject line
size	integer	Raw message size in bytes
has_attachments	boolean	Whether the message has attachments
is_read	boolean	Always false for new messages
is_starred	boolean	Always false for new messages
tags	array	Always [] for new messages
created_at	string	ISO 8601 UTC timestamp, second precision

Behavior

• Fire-and-forget: the webhook is dispatched in a background task and does not block message processing.
• 5-second timeout: if the endpoint doesn't respond within 5 seconds, the request is abandoned.
• No retries: failed deliveries are logged as warnings and not retried.
• No queue: webhooks are sent in real time as messages arrive. If the endpoint is down, those notifications are lost.
• 10 at a time: at most 10 deliveries are in flight at once; further ones wait for a free slot.
• No local or private IP literals: RustMail refuses to start if the URL's host is localhost or a loopback, private, link-local or other reserved IP address. Host names are not resolved, so a name that points at such an address is accepted.

Example: Slack Notification

Pair with a lightweight relay that transforms the payload into a Slack message:

rustmail serve --webhook-url https://relay.example.com/rustmail

The relay receives the JSON payload above and can POST a formatted message to Slack's Incoming Webhooks API.