Webhooks

MisarMail sends real-time webhook notifications to your HTTPS endpoint when email events occur. Configure webhooks in Settings → Webhooks.

Setup

Go to Settings → Webhooks → New Endpoint
Enter your HTTPS URL
Select the event types to subscribe to
Copy the signing secret

Event Types

Event	Trigger
`email.sent`	Email accepted and sent via SMTP
`email.delivered`	Delivery confirmed by recipient server
`email.opened`	Recipient opened the email
`email.clicked`	Recipient clicked a tracked link
`email.bounced`	Hard or soft bounce received
`email.complained`	Spam complaint (FBL report)
`email.unsubscribed`	Recipient clicked unsubscribe
`campaign.sent`	All campaign emails queued
`campaign.completed`	Campaign processing finished

Webhook Payload

All events share the same envelope format:

{
  "id":         "evt_550e8400e29b41d4a716446655440000",
  "type":       "email.opened",
  "created_at": "2026-03-20T12:00:00.000Z",
  "data": {
    "message_id":  "msg_abc123",
    "email":       "user@example.com",
    "campaign_id": "550e8400-e29b-41d4-a716-446655440001",
    "timestamp":   "2026-03-20T12:00:00.000Z"
  }
}

Bounce Event

{
  "type": "email.bounced",
  "data": {
    "message_id":      "msg_abc123",
    "email":           "user@example.com",
    "bounce_type":     "hard",
    "bounce_code":     "550",
    "bounce_message":  "User unknown"
  }
}

Signature Verification

Every webhook request includes an X-MisarMail-Signature header (HMAC-SHA256). Verify it to confirm the request is from MisarMail.

Verification Steps

Read the raw request body as bytes
Compute HMAC-SHA256 using your webhook signing secret
Compare with the header value using a constant-time comparison

import crypto from "crypto";

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  const sigBuffer = Buffer.from(signature, "hex");
  const expBuffer = Buffer.from(expected, "hex");
  if (sigBuffer.length !== expBuffer.length) return false;
  return crypto.timingSafeEqual(sigBuffer, expBuffer);
}

Next.js Route Handler

export async function POST(req) {
  const body = await req.text();
  const sig  = req.headers.get("x-misarmail-signature") ?? "";

  if (!verifyWebhookSignature(body, sig, process.env.MISARMAIL_WEBHOOK_SECRET)) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(body);
  switch (event.type) {
    case "email.bounced":      await handleBounce(event.data); break;
    case "email.unsubscribed": await handleUnsubscribe(event.data); break;
  }

  return new Response("OK");
}

Retry Policy

MisarMail retries failed deliveries (non-2xx or timeout after 30s) with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the event is marked as failed and no further retries occur.

Best Practices

Respond with 200 OK immediately and process the event asynchronously
Check event.id to deduplicate — the same event may be delivered more than once
Use idempotent handlers to safely handle retries