Webhooks

Delivery log and retries

Every event we POST to a webhook is recorded with its attempts: status code, response time, the first 500 characters of the response, and the error when there was one. Failed deliveries are retried on their own after 1 second, 30 seconds, 5 minutes and 30 minutes (5 attempts in total). After that the delivery is marked failed and stays in the log for 30 days. You can see the log under each webhook in the dashboard (Deliveries) and retry any entry from there or through the API.

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook_delivery",
      "id": "whd_01j9x4",
      "webhook_id": "wh_abc123",
      "event": "email.bounced",
      "status": "failed",
      "attempts": 5,
      "max_attempts": 5,
      "status_code": 503,
      "duration_ms": 87,
      "error": "Endpoint returned 503",
      "response": "upstream unavailable",
      "attempt_log": [{ "at": "2026-09-03T08:00:00.000Z", "status_code": 503, "duration_ms": 91, "error": "Endpoint returned 503" }],
      "next_attempt_at": null,
      "delivered_at": null,
      "created_at": "2026-09-03T08:00:00.000Z"
    }
  ]
}

{ "object": "webhook_delivery", "id": "whd_01j9x4", "event": "email.bounced", "status": "failed", "payload": "{"type":"email.bounced",...}" }

{ "success": true, "message": "Delivered", "delivery": { "id": "whd_01j9x4", "status": "succeeded", "attempts": 6, "status_code": 200 } }

Event Types

SMTPfast stores and sends Resend-style prefixed email event names. Legacy unprefixed setup requests such as delivered are accepted and normalized to email.delivered.

Webhook Payload

Each webhook POST contains a JSON payload with the event details:

{
  "id": "evt_abc123",
  "type": "email.delivered",
  "email_id": "email_abc123",
  "to": "[email protected]",
  "timestamp": "2026-04-05T12:00:03Z",
  "data": {
    "smtp_response": "250 OK"
  }
}

The unsubscribed event fires when a recipient clicks the one-click List-Unsubscribe header on an email you sent within the last 30 days. The payload ties the opt-out back to the originating send so you can automate downstream actions (e.g. removing the contact from a CRM):

{
  "id": "evt_abc123",
  "type": "email.unsubscribed",
  "email_id": "email_abc123",
  "to": "[email protected]",
  "timestamp": "2026-04-06T08:14:22Z",
  "data": {
    "from": "[email protected]",
    "source": "list-unsubscribe"
  }
}

The originating email's delivery status stays at its terminal value (typically delivered) — an unsubscribe is a post-delivery recipient action, not a delivery outcome. If a recipient clicks a stale unsubscribe link from a send older than 30 days the suppression still takes effect, but no webhook fires because there is no email to attribute it to.

Send to Discord or Slack

Set format to discord or slack and SMTPfast posts a formatted, color-coded message to your channel instead of the standard JSON envelope. No relay or glue code: paste the channel's incoming webhook URL and pick the format (we also auto-detect discord.com and hooks.slack.com URLs for you). Because the chat platform owns the payload schema, these deliveries are not HMAC-signed.

Get a webhook URL: Discord → Server Settings → Integrations → Webhooks. Slack → create an app → Incoming Webhooks.

curl -X POST https://smtpfa.st/api/v1/webhooks \
  -H "Authorization: Bearer $SMTPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://discord.com/api/webhooks/123456789/your-token",
    "events": ["email.bounced", "email.complained", "email.failed"],
    "format": "discord"
  }'

A bounce then lands in the channel as an embed like:

⚠️ Email bounced
To: [email protected]
From: [email protected]
Bounce type: Permanent
SMTPfast

HMAC Signature Verification

Every webhook request includes a X-SMTPfast-Signature header. Verify this signature to ensure the request came from SMTPfast and was not tampered with.

The signature is an HMAC-SHA256 hash of the raw request body using your webhook signing secret.

import crypto from "crypto";

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
const isValid = verifyWebhook(
  rawBody,
  req.headers["x-smtpfast-signature"],
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).json({ error: "Invalid signature" });
}