Webhooks

Create a subscription

Create a signed HTTPS webhook subscription. Save its one-time signing secret.

POST/api/v1/webhooks/

Permission webhook

Email events need mailbox access

Subscribing to message events also requires read permission, selected mailbox IDs, and current mailbox grants.

Request headers

Idempotency-Keystringrequired

A unique key for this intentional action. Reuse it only with the same request input.

Maximum 128 characters

Request body

Send JSON with Content-Type: application/json.

urlstringrequired

Public HTTPS callback URL on port 443. Private networks and redirects are blocked.

Maximum 2,048 characters

eventsstring[]required

Exact event names to subscribe to.

mailbox_idsinteger[]

Mailbox IDs covered by this subscription. Email events require current grants.

Default: []

Responses

200Success

Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.

400Invalid request

Invalid input or missing idempotency key.

401Unauthenticated

Missing, expired, or revoked bearer credential.

403Forbidden

Wrong credential purpose, insufficient scope, or missing mailbox grant.

404Not found

Resource or message not found or unavailable to this integration.

409Conflict

Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.

413Too large

Request or message exceeds the supported size.

429Rate limited

Rate limited. Honor Retry-After before retrying.

500Internal server error

Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.

503Service unavailable

Integrations disabled or an upstream service unavailable.

See limits and errors for retry handling and the error envelope.

Example request

curl -X POST 'https://cherrymail.net/api/v1/webhooks/' \
  -H "Authorization: Bearer $CHERRYMAIL_API_KEY" \
  -H "Idempotency-Key: example-request-1042" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://your-app.example/cherrymail/events",
  "events": [
    "message.received"
  ],
  "mailbox_ids": [
    123
  ]
}'

Responseapplication/json

dataobjectrequired

Show child fields

operation_idstring · uuidrequired

Durable operation ID. Use GET /operations/{id}/ to inspect it.

statestringrequired

Values: running, pending, completed, uncertain

resultobject | nullrequired

Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain.

Show child fields

idstring · uuidrequired

urlstringrequired

eventsstring[]required

mailbox_idsinteger[]required

signing_secretstring

Shown only on the initial successful creation response. Omitted on idempotent replay and operation lookup; store it securely the first time.

request_idstring · uuidrequired

Request ID for support and correlation. Also returned in X-Request-ID.

Example

200 response body

{
  "data": {
    "operation_id": "6032a8b5-5ab8-4d3d-9104-d1e8162a1453",
    "state": "completed",
    "result": {
      "id": "5995bf69-cbf4-496e-b9d1-25c9d2095563",
      "url": "https://your-app.example/cherrymail/events",
      "events": [
        "message.received"
      ],
      "mailbox_ids": [
        123
      ],
      "signing_secret": "cm_wh_example_only_store_your_actual_secret_securely"
    }
  },
  "request_id": "650f28e8-c344-42e4-ae43-c61539f83119"
}

Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.

Response headers

Cache-Control: no-store

X-Request-ID

Same request ID as the JSON body.

RateLimit-Limit: 120;w=60

Per-credential limit and window.

RateLimit-Reset: 60

Rate-limit window in seconds.

Base URL
https://cherrymail.net/api/v1

View the OpenAPI contract ↗