Webhooks

Smail can send HTTPS callbacks when API emails are queued, delivered, fail, or are suppressed.

Events

Event	Description
`email.queued`	An email was accepted by the API and queued for delivery
`email.delivered`	All queued recipients for the email were delivered
`email.failed`	Delivery failed
`email.suppressed`	The email was not queued because a recipient is on the suppression list

Create an endpoint

curl https://api.smail.dev/api/v1/webhooks \
  -H "Authorization: Bearer $SMAIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/smail-webhooks",
    "events": ["email.queued", "email.delivered", "email.failed", "email.suppressed"]
  }'

The response includes a secret once. Store it and use it to verify signatures.

Payload

{
  "type": "email.delivered",
  "created_at": "2026-05-14T10:30:00Z",
  "data": {
    "email_id": "4fcffcaa-7d14-4c1b-9f84-e83c117a69da",
    "from": "noreply@example.com",
    "to": ["user@example.com"],
    "subject": "Welcome",
    "status": "delivered",
    "created_at": "2026-05-14T10:29:57Z"
  }
}

Signature headers

Every delivery includes:

Header	Description
`X-Smail-Webhook-Id`	Delivery ID
`X-Smail-Webhook-Timestamp`	Signing timestamp
`X-Smail-Webhook-Signature`	`v1=` HMAC-SHA256 signature

The signed value is:

delivery_id + "." + timestamp + "." + raw_request_body

Retries

Smail retries failed deliveries with exponential backoff. Delivery attempts can be inspected via GET /api/v1/webhook-deliveries.