Webhooks

Get a signed HTTP request on your server whenever an email is sent, bounces or fails.

How webhooks work

A webhook endpoint is a URL on your server. When something happens to an email, MailForge sends a POST request with a JSON description of the event to that URL. Your server answers with any 2xx status within 10 seconds to confirm it.

Events are written to the database together with the change that caused them, and sent by the worker. A slow receiver never slows down sending, and an event is not lost when your server is down for a while.

Create an endpoint

POST/api/v1/webhooksRequires webhooks:manage
curl -X POST https://mail.example.com/api/v1/webhooks \
  -H "Authorization: Bearer $MAILFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.acme.com/webhooks/mailforge",
    "description": "Production listener",
    "events": [
      "email.sent",
      "email.bounced",
      "email.failed"
    ]
  }'
Body parameters
urlstringrequired
Must start with https:// and be reachable from the public internet. Plain http and private addresses are only accepted in development.
descriptionstring
A note for yourself, up to 200 characters.
eventsstring[]
The event types to receive. Leave it out or send an empty list to receive every event.

Response

201 Created
{
  "data": {
    "id": "23ae8981-db82-4d29-96dd-e6b7f039b0d7",
    "url": "https://app.acme.com/webhooks/mailforge",
    "description": "Production listener",
    "events": [
      "email.sent",
      "email.bounced",
      "email.failed"
    ],
    "enabled": true,
    "consecutive_failures": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": "2026-11-20T20:02:41.805Z",
    "secret": "whsec_pu4FOd5gj5F1KC2OfZnyoP8p6dMAPu4D"
  }
}

secret is the signing secret of this endpoint. Store it on your server to verify requests. A workspace can have up to 20 endpoints.

Event types

EventSent when
email.scheduledAn email was accepted with a future scheduledAt.
email.sentA provider accepted the email.
email.delivery_delayedNo provider accepted the email on this attempt. It will be retried.
email.bouncedThe recipient address was permanently rejected.
email.failedThe email could not be sent and will not be retried.
email.suppressedRecipients were skipped because they are on the suppression list.
email.canceledA scheduled email was canceled.
inbound.receivedAn inbound email arrived.
domain.verifiedA domain passed its DNS check.

Payload

Every event has the same envelope: an id that is unique per event, the type, the time it was created and a data object.

email.failed
{
  "id": "evt_9734b177781723bbf11a97bf",
  "type": "email.failed",
  "created_at": "2026-11-20T20:02:42.041Z",
  "data": {
    "email_id": "b470785e-9386-4d40-acda-e58c884c7640",
    "from": "orders@acme.com",
    "to": ["customer@example.com"],
    "subject": "Order 94821 confirmed",
    "stream": "transactional",
    "tags": {},
    "created_at": "2026-11-20T20:02:42.034Z",
    "error": {
      "code": "simulated",
      "message": "Simulated delivery failure (test mode)."
    },
    "test_mode": true
  }
}

data always names the email with email_id. Depending on the event it also contains provider, error or suppressed (the skipped addresses). Events caused by a test key carry test_mode: true.

Each request has these headers:

HeaderContent
x-mailforge-eventThe event type, for example email.sent.
x-mailforge-signaturesha256= followed by the HMAC-SHA256 of the raw body as hex.
webhook-idThe event id. The same on every retry, so you can ignore duplicates.
webhook-timestampUnix time in seconds of this attempt.
webhook-signaturev1, followed by a base64 signature according to the Standard Webhooks specification.

Verify the signature

Anyone who knows your URL can post to it, so check the signature before you trust a request. Compute the HMAC-SHA256 of the raw request body with the endpoint's secret (the full string including whsec_) and compare it with the x-mailforge-signature header.

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.MAILFORGE_WEBHOOK_SECRET; // whsec_...

// Use the raw body. Parsing and re-serialising the JSON changes the bytes.
app.post("/webhooks/mailforge", express.raw({ type: "application/json" }), (req, res) => {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  const received = req.get("x-mailforge-signature") ?? "";

  const valid =
    expected.length === received.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
  if (!valid) return res.status(401).send("Invalid signature");

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.type === "email.bounced") {
    console.log("Bounced:", event.data.email_id);
  }
  res.sendStatus(200);
});

app.listen(4000);

The three webhook-* headers follow the Standard Webhooks specification. If you already use one of its libraries, pass it the secret and the headers and it verifies the request, including protection against replayed requests.

Retries and delivery log

If your server does not answer with a 2xx status within 10 seconds, MailForge tries again after 5 seconds, 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 5 hours and 10 hours. An event can therefore arrive more than once. Use webhook-id to recognise one you already handled.

GET/api/v1/webhooks/{id}/deliveriesRequires webhooks:read

Lists the most recent deliveries of an endpoint, newest first, with the payload, the status your server answered and the first 4 KB of its response. limit can be 1 to 200 and defaults to 50.

curl "https://mail.example.com/api/v1/webhooks/23ae8981-db82-4d29-96dd-e6b7f039b0d7/deliveries?limit=1" \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "data": [
    {
      "id": "69d9e368-5134-4770-b7ed-0c55931047c3",
      "event_type": "email.failed",
      "status": "success",
      "attempts": 1,
      "response_status": 200,
      "response_body": "ok",
      "duration_ms": 2,
      "last_error": null,
      "next_attempt_at": "2026-11-20T20:02:42.041Z",
      "created_at": "2026-11-20T20:02:42.041Z",
      "completed_at": "2026-11-20T20:02:42.046Z",
      "payload": {
        "id": "evt_9734b177781723bbf11a97bf",
        "type": "email.failed",
        "created_at": "2026-11-20T20:02:42.041Z",
        "data": {
          "email_id": "b470785e-9386-4d40-acda-e58c884c7640"
        }
      }
    }
  ]
}
POST/api/v1/webhooks/deliveries/{id}/retryRequires webhooks:manage

Sends one delivery again right away, for example after you fixed a bug on your side. Answers 202.

Manage endpoints

POST/api/v1/webhooks/{id}/testRequires webhooks:manage

Sends a sample email.sent event with test: true in data to this endpoint only. The result shows up in the delivery log a moment later.

curl -X POST https://mail.example.com/api/v1/webhooks/23ae8981-db82-4d29-96dd-e6b7f039b0d7/test \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
202 Accepted
{
  "ok": true,
  "queued": 1
}
GET/api/v1/webhooksRequires webhooks:read

Lists all endpoints under data and every event type that exists under eventTypes. GET /api/v1/webhooks/{id} returns one endpoint.

curl https://mail.example.com/api/v1/webhooks \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
PATCH/api/v1/webhooks/{id}Requires webhooks:manage

Changes url, description, events or enabled. Send only the fields you want to change. Set enabled to false to pause an endpoint.

curl -X PATCH https://mail.example.com/api/v1/webhooks/23ae8981-db82-4d29-96dd-e6b7f039b0d7 \
  -H "Authorization: Bearer $MAILFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
GET/api/v1/webhooks/{id}/secretRequires webhooks:manage

Shows the signing secret again.

Response
{
  "data": {
    "secret": "whsec_pu4FOd5gj5F1KC2OfZnyoP8p6dMAPu4D"
  }
}
DELETE/api/v1/webhooks/{id}Requires webhooks:manage

Deletes the endpoint and stops all deliveries to it.

curl -X DELETE https://mail.example.com/api/v1/webhooks/23ae8981-db82-4d29-96dd-e6b7f039b0d7 \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "ok": true,
  "id": "23ae8981-db82-4d29-96dd-e6b7f039b0d7"
}