title: "Webhooks" description: "Create and manage webhook endpoints for the organization, a pod or an inbox: set custom headers, send test events, list deliveries and replay failed ones." canonical: "https://machinemail.dev/docs/reference/api/webhooks"

Webhooks

Create and manage webhook endpoints for the organization, a pod or an inbox: set custom headers, send test events, list deliveries and replay failed ones.

Source: https://machinemail.dev/docs/reference/api/webhooks

List Webhooks in Inbox

GET /v0/inboxes/{inbox_id}/webhooks

Same as List Webhooks (GET /v0/webhooks), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Query parameters

Response

200 A page of webhooks (application/json)

Each item of webhooks is a Webhook:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "webhooks": [
    {
      "webhook_id": "whk_01k6x3c2jp0000f2p8rw4a7h9k",
      "url": "https://example.com/webhooks/machinemail",
      "event_types": ["message.received"],
      "pod_ids": ["pod_01k6x2m9qd0001b8j4mr0w3d5f"],
      "inbox_ids": ["agent@machinemail.dev"],
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "inbox_id": "agent@machinemail.dev",
      "secret": "whsec_0123456789abcdef",
      "enabled": true,
      "updated_at": "2026-10-01T12:00:00.000Z",
      "created_at": "2026-10-01T12:00:00.000Z",
      "client_id": "my-client-id",
      "status": "active",
      "header_names": ["string"],
      "headers_updated_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Create Webhook in Inbox

POST /v0/inboxes/{inbox_id}/webhooks

Same as Create Webhook (POST /v0/webhooks), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_create.

Path parameters

Request body

Content type: application/json.

Response

200 A webhook with this client_id already exists; it is returned unchanged. (application/json)

201 Created (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/machinemail",
  "event_types": [
    "message.received"
  ]
}'

{
  "webhook_id": "whk_01k6x3c2jp0000f2p8rw4a7h9k",
  "url": "https://example.com/webhooks/machinemail",
  "event_types": ["message.received"],
  "pod_ids": ["pod_01k6x2m9qd0001b8j4mr0w3d5f"],
  "inbox_ids": ["agent@machinemail.dev"],
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "secret": "whsec_0123456789abcdef",
  "enabled": true,
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z",
  "client_id": "my-client-id",
  "status": "active",
  "header_names": ["string"],
  "headers_updated_at": "2026-10-01T12:00:00.000Z"
}

Get Webhook in Inbox

GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id}

Same as Get Webhook (GET /v0/webhooks/{webhook_id}), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Response

200 The webhook (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Webhook in Inbox

PATCH /v0/inboxes/{inbox_id}/webhooks/{webhook_id}

Same as Update Webhook (PATCH /v0/webhooks/{webhook_id}), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated webhook (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "message.received"
  ],
  "url": "https://example.com/webhooks/machinemail"
}'

Delete Webhook in Inbox

DELETE /v0/inboxes/{inbox_id}/webhooks/{webhook_id}

Same as Delete Webhook (DELETE /v0/webhooks/{webhook_id}), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_delete.

Path parameters

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

List Deliveries in Inbox

GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/deliveries

Same as List Deliveries (GET /v0/webhooks/{webhook_id}/deliveries), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Query parameters

Response

200 A page of deliveries (application/json)

Each item of deliveries is a WebhookDelivery:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "deliveries": [
    {
      "delivery_id": "dlv_01k6x3f1ns0000j5s1vz7d0m2p",
      "webhook_id": "whk_01k6x3c2jp0000f2p8rw4a7h9k",
      "event_id": "evt_01k6x3g4pt0000k6t2wa8e1n3q",
      "event_type": "message.received",
      "attempt": 1,
      "status": "pending",
      "response_status": 1,
      "response_body": "string",
      "next_attempt_at": "2026-10-01T12:00:00.000Z",
      "last_error": "string",
      "delivered_at": "2026-10-01T12:00:00.000Z",
      "created_at": "2026-10-01T12:00:00.000Z",
      "updated_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Replay Delivery in Inbox

POST /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/replay

Same as Replay Delivery (POST /v0/webhooks/{webhook_id}/deliveries/{delivery_id}/replay), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Response

200 The new delivery (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries/dlv_01k6x3f1ns0000j5s1vz7d0m2p/replay" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "delivery_id": "dlv_01k6x3f1ns0000j5s1vz7d0m2p",
  "webhook_id": "whk_01k6x3c2jp0000f2p8rw4a7h9k",
  "event_id": "evt_01k6x3g4pt0000k6t2wa8e1n3q",
  "event_type": "message.received",
  "attempt": 1,
  "status": "pending",
  "response_status": 1,
  "response_body": "string",
  "next_attempt_at": "2026-10-01T12:00:00.000Z",
  "last_error": "string",
  "delivered_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

Get Webhook Headers in Inbox

GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers

Same as Get Webhook Headers (GET /v0/webhooks/{webhook_id}/headers), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Response

200 The header names (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "header_names": ["string"],
  "headers_updated_at": "2026-10-01T12:00:00.000Z"
}

Update Webhook Headers in Inbox

PATCH /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers

Same as Update Webhook Headers (PATCH /v0/webhooks/{webhook_id}/headers), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Request body

Content type: application/json.

Sets, replaces or removes custom delivery headers; the headers you do not name are unchanged. Give at least one of headers (each name is added, or replaces the value of the header of that name in any case) or remove_headers. A name cannot be both set and removed in one request.

Response

204 Updated

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Send Test Event in Inbox

POST /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/test

Same as Send Test Event (POST /v0/webhooks/{webhook_id}/test), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Response

200 The test delivery (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/test" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

List Webhooks in Pod

GET /v0/pods/{pod_id}/webhooks

Same as List Webhooks (GET /v0/webhooks), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Query parameters

Response

200 A page of webhooks (application/json)

Each item of webhooks is a Webhook:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Create Webhook in Pod

POST /v0/pods/{pod_id}/webhooks

Same as Create Webhook (POST /v0/webhooks), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_create.

Path parameters

Request body

Content type: application/json.

Response

200 A webhook with this client_id already exists; it is returned unchanged. (application/json)

201 Created (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/machinemail",
  "event_types": [
    "message.received"
  ]
}'

Get Webhook in Pod

GET /v0/pods/{pod_id}/webhooks/{webhook_id}

Same as Get Webhook (GET /v0/webhooks/{webhook_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Response

200 The webhook (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Webhook in Pod

PATCH /v0/pods/{pod_id}/webhooks/{webhook_id}

Same as Update Webhook (PATCH /v0/webhooks/{webhook_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated webhook (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "message.received"
  ],
  "url": "https://example.com/webhooks/machinemail"
}'

Delete Webhook in Pod

DELETE /v0/pods/{pod_id}/webhooks/{webhook_id}

Same as Delete Webhook (DELETE /v0/webhooks/{webhook_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_delete.

Path parameters

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

List Deliveries in Pod

GET /v0/pods/{pod_id}/webhooks/{webhook_id}/deliveries

Same as List Deliveries (GET /v0/webhooks/{webhook_id}/deliveries), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Query parameters

Response

200 A page of deliveries (application/json)

Each item of deliveries is a WebhookDelivery:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Replay Delivery in Pod

POST /v0/pods/{pod_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/replay

Same as Replay Delivery (POST /v0/webhooks/{webhook_id}/deliveries/{delivery_id}/replay), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Response

200 The new delivery (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries/dlv_01k6x3f1ns0000j5s1vz7d0m2p/replay" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Get Webhook Headers in Pod

GET /v0/pods/{pod_id}/webhooks/{webhook_id}/headers

Same as Get Webhook Headers (GET /v0/webhooks/{webhook_id}/headers), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Response

200 The header names (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "header_names": ["string"],
  "headers_updated_at": "2026-10-01T12:00:00.000Z"
}

Update Webhook Headers in Pod

PATCH /v0/pods/{pod_id}/webhooks/{webhook_id}/headers

Same as Update Webhook Headers (PATCH /v0/webhooks/{webhook_id}/headers), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Request body

Content type: application/json.

Response

204 Updated

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Send Test Event in Pod

POST /v0/pods/{pod_id}/webhooks/{webhook_id}/test

Same as Send Test Event (POST /v0/webhooks/{webhook_id}/test), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Response

200 The test delivery (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/test" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

List Webhooks

GET /v0/webhooks

With an organization credential, every webhook of the organization, paginated. With a pod or inbox credential (or under a scoped path), the webhooks in that scope from the newest 500, in one page without next_page_token.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Query parameters

Response

200 A page of webhooks (application/json)

Each item of webhooks is a Webhook:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/webhooks" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Create Webhook

POST /v0/webhooks

The response includes secret (whsec_...), the key of the X-MachineMail-Signature HMAC. See the webhooks section of this document for the request MachineMail sends for each event type.

Under /v0/pods/{pod_id} or /v0/inboxes/{inbox_id}, or with a pod- or inbox-scoped credential, the webhook belongs to that pod or inbox (pod_id, inbox_id) and never receives events outside it.

A webhook delivers no event its creator could not read: each listed event type needs its read permission (message.* needs message_read, inbox.* inbox_read, domain.* domain_read, draft.* draft_read, webhook.test webhook_read), else 403. An empty event_types from a credential without all of them is stored as the types it may read (403 when there are none).

Custom request headers in headers are sent with every delivery (for example Authorization: Bearer <token> for an endpoint that requires it). Their values are write-only: responses list only header_names.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_create.

Request body

Content type: application/json.

Response

200 A webhook with this client_id already exists; it is returned unchanged. (application/json)

201 Created (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/webhooks" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/machinemail",
  "event_types": [
    "message.received"
  ]
}'

Get Webhook

GET /v0/webhooks/{webhook_id}

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Response

200 The webhook (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Webhook

PATCH /v0/webhooks/{webhook_id}

Fields you omit are unchanged. Webhooks are never disabled automatically after failed deliveries; enabled: false is the only way to disable one. New event_types follow the same permission rule as POST /v0/webhooks, and changing url needs the read permission of every event type the webhook delivers (403 otherwise).

headers replaces the custom delivery headers in full, null or {} removes them, and omitting it keeps them. While a webhook has custom headers, changing url to another origin (scheme, host or port) needs headers in the same request (400 otherwise), so header values never follow the webhook to a new server unless you send them again.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated webhook (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "message.received"
  ],
  "url": "https://example.com/webhooks/machinemail"
}'

Delete Webhook

DELETE /v0/webhooks/{webhook_id}

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_delete.

Path parameters

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

List Deliveries

GET /v0/webhooks/{webhook_id}/deliveries

Delivery attempts of the webhook, one per event (a replay is a new delivery).

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Query parameters

Response

200 A page of deliveries (application/json)

Each item of deliveries is a WebhookDelivery:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Replay Delivery

POST /v0/webhooks/{webhook_id}/deliveries/{delivery_id}/replay

Queues a new delivery of the same event to the webhook and attempts it right away, even when the webhook is disabled. Returns the new delivery after that attempt.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Response

200 The new delivery (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries/dlv_01k6x3f1ns0000j5s1vz7d0m2p/replay" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Get Webhook Headers

GET /v0/webhooks/{webhook_id}/headers

Names of the custom HTTP headers sent with every delivery to this webhook. Values are write-only and never returned.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_read.

Path parameters

Response

200 The header names (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "header_names": ["string"],
  "headers_updated_at": "2026-10-01T12:00:00.000Z"
}

Update Webhook Headers

PATCH /v0/webhooks/{webhook_id}/headers

Sets, replaces or removes custom delivery headers in one atomic change; headers you do not name keep their values. To replace the whole set (or clear it), use headers on PATCH /v0/webhooks/{webhook_id}. Values remain write-only.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Request body

Content type: application/json.

Response

204 Updated

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Send Test Event

POST /v0/webhooks/{webhook_id}/test

Records a webhook.test event and delivers it to this webhook only (whatever its event_types, even when disabled), then returns the delivery after the first attempt.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: webhook_update.

Path parameters

Response

200 The test delivery (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/test" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"