Mail notifications

A mail notification is a URL subscribed to a mailbox. When a message arrives, mailcatchr POSTs a JSON event to it. Configure them from the mailbox page under Settings → Mail notifications.

Events

Event	When
message.received	Inbound mail landed in the mailbox
message.outbound.sent	An outbound send was accepted by the provider
message.outbound.bounced	An outbound send bounced
message.outbound.complaint	A recipient reported an outbound send as spam

Verifying a delivery

Every request carries:

Header	Contents
X-Mailcatchr-Event	The event name
X-Mailcatchr-Delivery	A unique id per delivery attempt
X-Mailcatchr-Timestamp	Unix seconds when it was sent
X-Mailcatchr-Signature	sha256=<hex>

The signature is an HMAC-SHA256 over timestamp + "." + rawBody using the secret shown when the notification was created. Verify it before trusting the payload, and reject deliveries whose timestamp is more than five minutes old.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret: string, timestamp: string, rawBody: string, header: string) {
  const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  return expected.length === header.length && timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Delivery rules

• HTTPS only. URLs that resolve to private or link-local addresses are refused.
• Failed deliveries are retried with backoff.
• Redirects are not followed.

Notifications versus interceptors

Mail notifications send webhooks about mail. Webhook interceptors receive webhooks from systems you are testing. They are separate features.