Developer Documentation

Webhooks

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

Mails.now can deliver inbox and sequencer events to your HTTPS endpoints. Register webhooks with a webhook permission API key.

Inbox 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

Sequencer events

  • sequencer.email.sent — an outbound sequencer email was sent
  • sequencer.email.opened — a recipient opened a tracked sequencer email
  • sequencer.email.clicked — a recipient clicked a tracked link
  • sequencer.lead.replied — a lead replied to a sequencer email
  • sequencer.lead.bounced — a hard bounce was detected for a lead
  • sequencer.lead.unsubscribed — a lead unsubscribed from sequencer mail
  • sequencer.campaign.completed — all enrollments in a campaign finished

Register a webhook

Inbox-only example:

Request Example

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/mailsnow",
    "events": ["email.received", "email.read", "email.deleted"],
    "is_active": true
  }'

Inbox and sequencer events:

Request Example

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/mailsnow",
    "events": [
      "email.received",
      "sequencer.email.sent",
      "sequencer.lead.replied",
      "sequencer.campaign.completed"
    ],
    "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

Success Response

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

Full REST reference: API docs