Webhooks Relay

Avoid pulling. Mailzan pushes inbound SMTP email events directly to your application backend servers via secure, real-time HTTP webhooks.

Payload Structure

Webhooks transmit standard JSON payloads detailing parsed mail headers, plain text, HTML segments, and attachment metadata lists.

{
  "event": "email.received",
  "timestamp": "2026-07-05T03:38:00Z",
  "data": {
    "id": "e21a8f90-1c88-4f81-ba55-9382f1b0a88e",
    "from": "sender@external.com",
    "to": "test-box@yourdomain.com",
    "subject": "Verification Code: 49201",
    "text": "Your code is 49201. Please verify your registration.",
    "html": "<p>Your code is <strong>49201</strong></p>"
  }
}
      

HMAC SHA256 Signature Verification

For security, each webhook request includes a custom header: x-tmaas-signature. This signature is generated using a keyed hash (HMAC SHA-256) of the raw payload body and your webhook target signing secret.

Retry Policy

If your target endpoint returns an HTTP error code (e.g. 500, 503, 404) or times out, our background worker queue (powered by BullMQ) schedules automated retries using an exponential backoff strategy for up to 5 times.