Developer Documentation

Webhooks

Event delivery for email.received, email.read, and email.deleted.

MailAPI can deliver inbox events to your HTTPS endpoints. Register webhooks with a webhook permission API key.

Events

email.received — a new email was stored for a tenant mailbox
email.read — an email was marked read via API or dashboard
email.deleted — an email was soft-deleted via API or dashboard

Register a webhook

curl --fail-with-body --silent --show-error \
  -X POST "$APP_URL/api/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/mailapi",
    "events": ["email.received", "email.read", "email.deleted"],
    "is_active": true
  }'

Manage webhooks

Method	Path	Description
GET	`/api/v1/webhooks`	List tenant webhooks
PATCH	`/api/v1/webhooks/{id}`	Update URL, events, or active flag
DELETE	`/api/v1/webhooks/{id}`	Delete webhook

Delivery security

Each delivery includes:

X-Webhook-Timestamp — Unix timestamp
X-Webhook-Signature — HMAC-SHA256 of {timestamp}.{raw_json_body} using the webhook secret

Verify signatures on your receiver before processing payloads.

Payload shape

{
  "event": "email.received",
  "timestamp": 1777290021,
  "data": {
    "email_id": 101,
    "mailbox_id": 10
  }
}

Full REST reference: API docs