mailnix Docs
    mailnix / Outbound webhooks

    API reference

    Outbound webhooks

    Subscribe a URL to delivered / bounced / complained / failed message events. Stripe-style HMAC signing. Durable retry with backoff.

    Subscribe to events

    POST /v1/webhooks
Authorization: Bearer mnx_live_…
Content-Type:  application/json

{
  "name":        "billing-receipts",
  "target_url":  "https://api.yourapp.com/mailnix",
  "event_types": ["delivered", "bounced", "complained"]
}

# response (the hmac_secret is shown once)
{
  "id":          "wh_7c2d…",
  "hmac_secret": "whsec_…",
  "target_url":  "https://api.yourapp.com/mailnix"
}

    Omit event_types (or pass an empty array) to subscribe to every event. The HMAC secret is exposed once and never re-displayed; rotate via POST /v1/webhooks/{id}/rotate-secret.

    Verifying signatures

    Every webhook mailnix POSTs is signed:

    X-Mailnix-Signature: sha256=<hex(hmac_sha256(body, route_secret))>

    Verify before processing. Replays are deduped via the X-Mailnix-Delivery header (a UUID).

    Retries

    Schedule: 1m → 5m → 25m → 2h → 12h → 24h, then parked (no further retries). Inspect attempts at GET /v1/webhooks/{id}/attempts: per-row attempt_count, last_status_code, last_error.

    Event types

    • delivered
    • bounced
    • complained
    • failed
    • auto_suppressed (post-delivery suppression annotation)