Developer Portal

Which events can you receive? (A)

Up to 50 events per webhook, 20 webhooks per account. The technical name is what arrives in the type field of the envelope. The data payload of each type is documented in the API reference.

The envelope

Every event shares the same JSON envelope. Use id as an idempotency key: a retried delivery carries the same id.

{
  "id": "evt_5f2c…",
  "type": "email.delivered",
  "created": 1758000000,
  "apiVersion": "v3",
  "account": { "id": 12345, "name": "ACME" },
  "data": {
    "email": "[email protected]",
    "idSending": 987654,
    "sendingType": 3,
    "diagCode": "250 2.0.0 OK",
    "deliveredAt": "2026-09-16T08:03:41Z"
  }
}

Verify the signature

Each call carries X-Mailpro-Signature: t=<unix>,v1=<hex>. v1 is the HMAC-SHA256 of t + "." + raw body with the secret shown once at creation. Reject stale timestamps, answer 2xx within 10 seconds, process asynchronously.

On failure Mailpro retries 10 s → 1 min → 5 min → 30 min → 2 h → 6 h → 24 h, then disables the webhook after 10 consecutive failures (one click to reactivate).

// Node.js
const crypto = require("crypto");
function verify(rawBody, header, secret) {
  const t  = header.match(/t=([0-9]+)/)[1];
  const v1 = header.match(/v1=([0-9a-f]+)/)[1];
  const expected = crypto.createHmac("sha256", secret)
                         .update(t + "." + rawBody).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}