Sign in

v51

OpenAPI 3.0.0raw.githubusercontent.com2026-08-01267339950.6 KB
Mail: Webhooks

Create webhook

Create a webhook for the given mailbox. The generated secret is returned only in this response and is sent as a bearer token with every delivery.

post/api/mail/v1/mailboxes/{mailboxId}/webhooks

Path parameters

mailboxIdstring required
Example:AC1a2b3c4d5e6f7g

Mailbox resource ID

Request body

namestring required

Human-readable name for this webhook

descriptionstring nullable

Optional description of the webhook's purpose

eventsstring[] required

Events that trigger this webhook

status'active' | 'disabled' | 'paused'

Initial status of the webhook

urlstring required

Publicly reachable URL that receives the webhook POST requests

Example request

{
  "name": "New message notifier",
  "description": "Notifies our CRM when a new email arrives",
  "events": [
    "message.received"
  ],
  "status": "active",
  "url": "https://example.com/webhooks/incoming"
}

Response

Created response

idstring

Unique webhook identifier

namestring

Human-readable name for this webhook

descriptionstring nullable

Optional description of the webhook's purpose

eventsstring[]

Events that trigger this webhook

status'active' | 'disabled' | 'paused'

Current status of the webhook

urlstring

URL that receives webhook POST requests

secretstring

One-time webhook secret, returned only on creation. Sent as Authorization: Bearer <secret> with every delivery.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "019683f8-1234-7abc-8def-0123456789ab",
  "mailbox": {
    "id": "AC1a2b3c4d5e6f7g",
    "address": "user@example.com"
  },
  "name": "New message notifier",
  "description": "Notifies our CRM when a new email arrives",
  "events": [
    "message.received"
  ],
  "status": "active",
  "url": "https://example.com/webhooks/incoming",
  "secret": "4a6f8b2d1e9c3f7a0b5d8e2c4f1a7b3d9e6c2f8a1b4d7e0c3f6a9b2d5e8c1f4",
  "created_at": "2026-07-23T12:00:00Z",
  "updated_at": "2026-07-23T12:00:00Z"
}