[Skip to content](/content/docs/reference/api/webhooks#nd-page/index.html) [Skip to content](/content/docs/reference/api/webhooks#nd-page/index.html) \[01/30\]List Webhooks in Inbox | Method | Path | Summary | | --- | --- | --- | | `GET` | `/v0/inboxes/{inbox_id}/webhooks` | [List Webhooks in Inbox](/content/docs/reference/api/webhooks#list-webhooks-in-inbox/index.html) | | `POST` | `/v0/inboxes/{inbox_id}/webhooks` | [Create Webhook in Inbox](/content/docs/reference/api/webhooks#create-webhook-in-inbox/index.html) | | `GET` | `/v0/inboxes/{inbox_id}/webhooks/{webhook_id}` | [Get Webhook in Inbox](/content/docs/reference/api/webhooks#get-webhook-in-inbox/index.html) | | `PATCH` | `/v0/inboxes/{inbox_id}/webhooks/{webhook_id}` | [Update Webhook in Inbox](/content/docs/reference/api/webhooks#update-webhook-in-inbox/index.html) | | `DELETE` | `/v0/inboxes/{inbox_id}/webhooks/{webhook_id}` | [Delete Webhook in Inbox](/content/docs/reference/api/webhooks#delete-webhook-in-inbox/index.html) | | `GET` | `/v0/inboxes/{inbox_id}/webhooks/{webhook_id}/deliveries` | [List Deliveries in Inbox](/content/docs/reference/api/webhooks#list-deliveries-in-inbox/index.html) | | `POST` | `/v0/inboxes/{inbox_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/replay` | [Replay Delivery in Inbox](/content/docs/reference/api/webhooks#replay-delivery-in-inbox/index.html) | | `GET` | `/v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers` | [Get Webhook Headers in Inbox](/content/docs/reference/api/webhooks#get-webhook-headers-in-inbox/index.html) | | `PATCH` | `/v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers` | [Update Webhook Headers in Inbox](/content/docs/reference/api/webhooks#update-webhook-headers-in-inbox/index.html) | | `POST` | `/v0/inboxes/{inbox_id}/webhooks/{webhook_id}/test` | [Send Test Event in Inbox](/content/docs/reference/api/webhooks#send-test-event-in-inbox/index.html) | | `GET` | `/v0/pods/{pod_id}/webhooks` | [List Webhooks in Pod](/content/docs/reference/api/webhooks#list-webhooks-in-pod/index.html) | | `POST` | `/v0/pods/{pod_id}/webhooks` | [Create Webhook in Pod](/content/docs/reference/api/webhooks#create-webhook-in-pod/index.html) | | `GET` | `/v0/pods/{pod_id}/webhooks/{webhook_id}` | [Get Webhook in Pod](/content/docs/reference/api/webhooks#get-webhook-in-pod/index.html) | | `PATCH` | `/v0/pods/{pod_id}/webhooks/{webhook_id}` | [Update Webhook in Pod](/content/docs/reference/api/webhooks#update-webhook-in-pod/index.html) | | `DELETE` | `/v0/pods/{pod_id}/webhooks/{webhook_id}` | [Delete Webhook in Pod](/content/docs/reference/api/webhooks#delete-webhook-in-pod/index.html) | | `GET` | `/v0/pods/{pod_id}/webhooks/{webhook_id}/deliveries` | [List Deliveries in Pod](/content/docs/reference/api/webhooks#list-deliveries-in-pod/index.html) | | `POST` | `/v0/pods/{pod_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/replay` | [Replay Delivery in Pod](/content/docs/reference/api/webhooks#replay-delivery-in-pod/index.html) | | `GET` | `/v0/pods/{pod_id}/webhooks/{webhook_id}/headers` | [Get Webhook Headers in Pod](/content/docs/reference/api/webhooks#get-webhook-headers-in-pod/index.html) | | `PATCH` | `/v0/pods/{pod_id}/webhooks/{webhook_id}/headers` | [Update Webhook Headers in Pod](/content/docs/reference/api/webhooks#update-webhook-headers-in-pod/index.html) | | `POST` | `/v0/pods/{pod_id}/webhooks/{webhook_id}/test` | [Send Test Event in Pod](/content/docs/reference/api/webhooks#send-test-event-in-pod/index.html) | | `GET` | `/v0/webhooks` | [List Webhooks](/content/docs/reference/api/webhooks#list-webhooks/index.html) | | `POST` | `/v0/webhooks` | [Create Webhook](/content/docs/reference/api/webhooks#create-webhook/index.html) | | `GET` | `/v0/webhooks/{webhook_id}` | [Get Webhook](/content/docs/reference/api/webhooks#get-webhook/index.html) | | `PATCH` | `/v0/webhooks/{webhook_id}` | [Update Webhook](/content/docs/reference/api/webhooks#update-webhook/index.html) | | `DELETE` | `/v0/webhooks/{webhook_id}` | [Delete Webhook](/content/docs/reference/api/webhooks#delete-webhook/index.html) | | `GET` | `/v0/webhooks/{webhook_id}/deliveries` | [List Deliveries](/content/docs/reference/api/webhooks#list-deliveries/index.html) | | `POST` | `/v0/webhooks/{webhook_id}/deliveries/{delivery_id}/replay` | [Replay Delivery](/content/docs/reference/api/webhooks#replay-delivery/index.html) | | `GET` | `/v0/webhooks/{webhook_id}/headers` | [Get Webhook Headers](/content/docs/reference/api/webhooks#get-webhook-headers/index.html) | | `PATCH` | `/v0/webhooks/{webhook_id}/headers` | [Update Webhook Headers](/content/docs/reference/api/webhooks#update-webhook-headers/index.html) | | `POST` | `/v0/webhooks/{webhook_id}/test` | [Send Test Event](/content/docs/reference/api/webhooks#send-test-event/index.html) | ## [List Webhooks in Inbox](/content/docs/reference/api/webhooks\#list-webhooks-in-inbox/index.html) http ``` GET /v0/inboxes/{inbox_id}/webhooks ``` Same as List Webhooks (`GET /v0/webhooks`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. #### [Query parameters](/content/docs/reference/api/webhooks\#query-parameters/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Sort oldest first. #### [Response](/content/docs/reference/api/webhooks\#response/index.html) **200** A page of webhooks (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `webhooks` [Webhook\[\]](/content/docs/reference/api/objects#webhook/index.html) Required Ordered by created\_at, newest first unless ascending is set. Each item of `webhooks` is a [Webhook](/content/docs/reference/api/objects#webhook/index.html): FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. `event_types``("message.received" | "message.received.spam" | "message.received.quarantined" | "message.received.unauthenticated" | "message.received.blocked" | "message.sent" | "message.delivered" | "message.bounced" | "message.complained" | "message.rejected" | "domain.verified" | "domain.updated" | "inbox.created" | "inbox.expired" | "draft.sent" | "webhook.test" | "trusted_domain.created" | "trusted_domain.updated" | "trusted_domain.deleted")[]`Required Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `404` | Not found. Also returned for resources outside the credential scope. | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example/index.html) Request ``` curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "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](/content/docs/reference/api/webhooks\#create-webhook-in-inbox/index.html) http ``` POST /v0/inboxes/{inbox_id}/webhooks ``` Same as Create Webhook (`POST /v0/webhooks`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_create`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-1/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. #### [Request body](/content/docs/reference/api/webhooks\#request-body/index.html) Content type: `application/json`. FieldDescription `url``string`Required Endpoint URL: a public http(s) URL (private and loopback addresses are rejected, and re-checked before every delivery). `event_types``("message.received" | "message.received.spam" | "message.received.quarantined" | "message.received.unauthenticated" | "message.received.blocked" | "message.sent" | "message.delivered" | "message.bounced" | "message.complained" | "message.rejected" | "domain.verified" | "domain.updated" | "inbox.created" | "inbox.expired" | "draft.sent" | "webhook.test" | "trusted_domain.created" | "trusted_domain.updated" | "trusted_domain.deleted")[]` Event types the webhook receives. Omit it or send an empty array to receive every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `client_id``string` Idempotency key: a create with a client\_id already used in the organization returns that webhook with 200, or 409 when that webhook is outside the pod or inbox of the API key or route. `inbox_ids``string[]` Only deliver events of these inboxes. `pod_ids``string[]` Only deliver events of these pods. `headers``Record` Custom HTTP headers sent with every delivery to this webhook (every attempt, retry, replay and test event), alongside the X-MachineMail-\* headers, for example {"Authorization": "Bearer "} for an endpoint that requires one. Values are write-only: they are stored encrypted and no response returns them; reads list the names (header\_names). The headers are not part of the signed payload: X-MachineMail-Signature covers the body only. At most 10 headers. Names are HTTP tokens of up to 64 characters, compared without regard to case; values are printable ASCII (no line breaks or control characters) of up to 4096 characters, with surrounding spaces removed, and names plus values total at most 8192 bytes. Reserved names are refused with 400: Host, Content-Length, Content-Type, Content-Encoding, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, Expect, User-Agent, Accept-Encoding, and every name starting with Proxy-, Sec-, X-MachineMail-, Svix- or Webhook-. Authorization and Cookie are allowed. #### [Response](/content/docs/reference/api/webhooks\#response-1/index.html) **200** A webhook with this client\_id already exists; it is returned unchanged. (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. **201** Created (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-1/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-1/index.html) Request ``` 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"\ ] }' ``` Response 200 ``` { "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](/content/docs/reference/api/webhooks\#get-webhook-in-inbox/index.html) http ``` GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id} ``` Same as Get Webhook (`GET /v0/webhooks/{webhook_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-2/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-2/index.html) **200** The webhook (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-2/index.html) | Status | Meaning | | --- | --- | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `404` | Not found. Also returned for resources outside the credential scope. | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-2/index.html) Request ``` curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Update Webhook in Inbox](/content/docs/reference/api/webhooks\#update-webhook-in-inbox/index.html) http ``` PATCH /v0/inboxes/{inbox_id}/webhooks/{webhook_id} ``` Same as Update Webhook (`PATCH /v0/webhooks/{webhook_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-3/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `webhook_id``string`Required ID of the webhook. #### [Request body](/content/docs/reference/api/webhooks\#request-body-1/index.html) Content type: `application/json`. FieldDescription Replaces the subscribed event types in full (not a merge). An empty array subscribes to every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. Omit it to keep the types. `enabled``boolean` false disables the webhook: no new deliveries are queued (deliveries already queued are still attempted). true enables it again. Events that occurred while it was disabled are not delivered later. `add_inbox_ids``string[]` Inboxes to add to inbox\_ids. `remove_inbox_ids``string[]` Inboxes to remove from inbox\_ids. `add_pod_ids``string[]` Pods to add to pod\_ids. `remove_pod_ids``string[]` Pods to remove from pod\_ids. `url``string` New endpoint URL: a public http(s) URL. `headers``Record | null` Replaces the custom delivery headers in full (not a merge): the webhook then sends exactly these. null or {} removes them all; omit it to keep them. To change one header and keep the others, use PATCH /v0/webhooks/{webhook\_id}/headers. Values are write-only. At most 10 headers. Names are HTTP tokens of up to 64 characters, compared without regard to case; values are printable ASCII (no line breaks or control characters) of up to 4096 characters, with surrounding spaces removed, and names plus values total at most 8192 bytes. Reserved names are refused with 400: Host, Content-Length, Content-Type, Content-Encoding, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, Expect, User-Agent, Accept-Encoding, and every name starting with Proxy-, Sec-, X-MachineMail-, Svix- or Webhook-. Authorization and Cookie are allowed. #### [Response](/content/docs/reference/api/webhooks\#response-3/index.html) **200** The updated webhook (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-3/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-3/index.html) Request ``` 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" }' ``` Response 200 ## [Delete Webhook in Inbox](/content/docs/reference/api/webhooks\#delete-webhook-in-inbox/index.html) http ``` DELETE /v0/inboxes/{inbox_id}/webhooks/{webhook_id} ``` Same as Delete Webhook (`DELETE /v0/webhooks/{webhook_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_delete`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-4/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-4/index.html) **200** Deleted (`application/json`) FieldDescription `ok``true`Required #### [Errors](/content/docs/reference/api/webhooks\#errors-4/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-4/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "ok": true } ``` ## [List Deliveries in Inbox](/content/docs/reference/api/webhooks\#list-deliveries-in-inbox/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-5/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `webhook_id``string`Required ID of the webhook. #### [Query parameters](/content/docs/reference/api/webhooks\#query-parameters-1/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Sort oldest first. `status``"pending" | "delivered" | "failed"` Only deliveries with this status. #### [Response](/content/docs/reference/api/webhooks\#response-5/index.html) **200** A page of deliveries (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `deliveries` [WebhookDelivery\[\]](/content/docs/reference/api/objects#webhookdelivery/index.html) Required Ordered by created\_at, newest first unless ascending is set. Each item of `deliveries` is a [WebhookDelivery](/content/docs/reference/api/objects#webhookdelivery/index.html): FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `event_type``"message.received" | "message.received.spam" | "message.received.quarantined" | "message.received.unauthenticated" | "message.received.blocked" | "message.sent" | "message.delivered" | "message.bounced" | "message.complained" | "message.rejected" | "domain.verified" | "domain.updated" | "inbox.created" | "inbox.expired" | "draft.sent" | "webhook.test" | "trusted_domain.created" | "trusted_domain.updated" | "trusted_domain.deleted"`Required Type of event. AgentMail has no message.received.quarantined, domain.updated, inbox.created, inbox.expired, draft.sent or webhook.test; MachineMail does not emit message.opened or calendar.event.\*. domain.updated is sent whenever a DNS check changes the domain status or a record status (the change to VERIFIED also sends domain.verified). trusted\_domain.created, .updated and .deleted (MachineMail) record changes to trusted domains. Webhooks and WebSocket subscriptions receive domain.updated and the trusted\_domain.\* types only when their event\_types list them, while the SSE stream and the event log always include them. `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-5/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-5/index.html) Request ``` curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "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](/content/docs/reference/api/webhooks\#replay-delivery-in-inbox/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-6/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `webhook_id``string`Required ID of the webhook. `delivery_id``string`Required ID of the delivery to replay. #### [Response](/content/docs/reference/api/webhooks\#response-6/index.html) **200** The new delivery (`application/json`) FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-6/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-6/index.html) Request ``` 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" ``` Response 200 ``` { "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](/content/docs/reference/api/webhooks\#get-webhook-headers-in-inbox/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-7/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-7/index.html) **200** The header names (`application/json`) FieldDescription `header_names``string[]`Required Names of the custom delivery headers of this webhook, as they were set. Values are never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-7/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-7/index.html) Request ``` curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "header_names": ["string"], "headers_updated_at": "2026-10-01T12:00:00.000Z" } ``` ## [Update Webhook Headers in Inbox](/content/docs/reference/api/webhooks\#update-webhook-headers-in-inbox/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-8/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `webhook_id``string`Required ID of the webhook. #### [Request body](/content/docs/reference/api/webhooks\#request-body-2/index.html) 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. FieldDescription `headers``Record` `remove_headers``string[]` Names of custom headers to remove (any case). Names that are not set are ignored. #### [Response](/content/docs/reference/api/webhooks\#response-8/index.html) **204** Updated #### [Errors](/content/docs/reference/api/webhooks\#errors-8/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-8/index.html) Request ``` 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](/content/docs/reference/api/webhooks\#send-test-event-in-inbox/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-9/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-9/index.html) **200** The test delivery (`application/json`) FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-9/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-9/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/test" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [List Webhooks in Pod](/content/docs/reference/api/webhooks\#list-webhooks-in-pod/index.html) http ``` GET /v0/pods/{pod_id}/webhooks ``` Same as List Webhooks (`GET /v0/webhooks`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-10/index.html) FieldDescription `pod_id``string`Required ID of the pod. #### [Query parameters](/content/docs/reference/api/webhooks\#query-parameters-2/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Sort oldest first. #### [Response](/content/docs/reference/api/webhooks\#response-10/index.html) **200** A page of webhooks (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `webhooks` [Webhook\[\]](/content/docs/reference/api/objects#webhook/index.html) Required Ordered by created\_at, newest first unless ascending is set. Each item of `webhooks` is a [Webhook](/content/docs/reference/api/objects#webhook/index.html): FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-10/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-10/index.html) Request ``` curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Create Webhook in Pod](/content/docs/reference/api/webhooks\#create-webhook-in-pod/index.html) http ``` POST /v0/pods/{pod_id}/webhooks ``` Same as Create Webhook (`POST /v0/webhooks`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_create`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-11/index.html) FieldDescription `pod_id``string`Required ID of the pod. #### [Request body](/content/docs/reference/api/webhooks\#request-body-3/index.html) Content type: `application/json`. FieldDescription `url``string`Required Endpoint URL: a public http(s) URL (private and loopback addresses are rejected, and re-checked before every delivery). `client_id``string` `inbox_ids``string[]` Only deliver events of these inboxes. `pod_ids``string[]` Only deliver events of these pods. `headers``Record` #### [Response](/content/docs/reference/api/webhooks\#response-11/index.html) **200** A webhook with this client\_id already exists; it is returned unchanged. (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. **201** Created (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-11/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-11/index.html) Request ``` 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"\ ] }' ``` Response 200 ## [Get Webhook in Pod](/content/docs/reference/api/webhooks\#get-webhook-in-pod/index.html) http ``` GET /v0/pods/{pod_id}/webhooks/{webhook_id} ``` Same as Get Webhook (`GET /v0/webhooks/{webhook_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-12/index.html) FieldDescription `pod_id``string`Required ID of the pod. `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-12/index.html) **200** The webhook (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-12/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-12/index.html) Request ``` curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Update Webhook in Pod](/content/docs/reference/api/webhooks\#update-webhook-in-pod/index.html) http ``` PATCH /v0/pods/{pod_id}/webhooks/{webhook_id} ``` Same as Update Webhook (`PATCH /v0/webhooks/{webhook_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-13/index.html) FieldDescription `pod_id``string`Required ID of the pod. `webhook_id``string`Required ID of the webhook. #### [Request body](/content/docs/reference/api/webhooks\#request-body-4/index.html) Content type: `application/json`. FieldDescription `enabled``boolean` `add_inbox_ids``string[]` Inboxes to add to inbox\_ids. `remove_inbox_ids``string[]` Inboxes to remove from inbox\_ids. `add_pod_ids``string[]` Pods to add to pod\_ids. `remove_pod_ids``string[]` Pods to remove from pod\_ids. `url``string` New endpoint URL: a public http(s) URL. `headers``Record | null` #### [Response](/content/docs/reference/api/webhooks\#response-13/index.html) **200** The updated webhook (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-13/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-13/index.html) Request ``` 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" }' ``` Response 200 ## [Delete Webhook in Pod](/content/docs/reference/api/webhooks\#delete-webhook-in-pod/index.html) http ``` DELETE /v0/pods/{pod_id}/webhooks/{webhook_id} ``` Same as Delete Webhook (`DELETE /v0/webhooks/{webhook_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_delete`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-14/index.html) FieldDescription `pod_id``string`Required ID of the pod. `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-14/index.html) **200** Deleted (`application/json`) FieldDescription `ok``true`Required #### [Errors](/content/docs/reference/api/webhooks\#errors-14/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-14/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "ok": true } ``` ## [List Deliveries in Pod](/content/docs/reference/api/webhooks\#list-deliveries-in-pod/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-15/index.html) FieldDescription `pod_id``string`Required ID of the pod. `webhook_id``string`Required ID of the webhook. #### [Query parameters](/content/docs/reference/api/webhooks\#query-parameters-3/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Sort oldest first. `status``"pending" | "delivered" | "failed"` Only deliveries with this status. #### [Response](/content/docs/reference/api/webhooks\#response-15/index.html) **200** A page of deliveries (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `deliveries` [WebhookDelivery\[\]](/content/docs/reference/api/objects#webhookdelivery/index.html) Required Ordered by created\_at, newest first unless ascending is set. Each item of `deliveries` is a [WebhookDelivery](/content/docs/reference/api/objects#webhookdelivery/index.html): FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-15/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-15/index.html) Request ``` curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Replay Delivery in Pod](/content/docs/reference/api/webhooks\#replay-delivery-in-pod/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-16/index.html) FieldDescription `pod_id``string`Required ID of the pod. `webhook_id``string`Required ID of the webhook. `delivery_id``string`Required ID of the delivery to replay. #### [Response](/content/docs/reference/api/webhooks\#response-16/index.html) **200** The new delivery (`application/json`) FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-16/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-16/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries/dlv_01k6x3f1ns0000j5s1vz7d0m2p/replay" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Get Webhook Headers in Pod](/content/docs/reference/api/webhooks\#get-webhook-headers-in-pod/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-17/index.html) FieldDescription `pod_id``string`Required ID of the pod. `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-17/index.html) **200** The header names (`application/json`) FieldDescription `header_names``string[]`Required Names of the custom delivery headers of this webhook, as they were set. Values are never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-17/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-17/index.html) Request ``` curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "header_names": ["string"], "headers_updated_at": "2026-10-01T12:00:00.000Z" } ``` ## [Update Webhook Headers in Pod](/content/docs/reference/api/webhooks\#update-webhook-headers-in-pod/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-18/index.html) FieldDescription `pod_id``string`Required ID of the pod. `webhook_id``string`Required ID of the webhook. #### [Request body](/content/docs/reference/api/webhooks\#request-body-5/index.html) Content type: `application/json`. FieldDescription `headers``Record` `remove_headers``string[]` Names of custom headers to remove (any case). Names that are not set are ignored. #### [Response](/content/docs/reference/api/webhooks\#response-18/index.html) **204** Updated #### [Errors](/content/docs/reference/api/webhooks\#errors-18/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-18/index.html) Request ``` 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](/content/docs/reference/api/webhooks\#send-test-event-in-pod/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-19/index.html) FieldDescription `pod_id``string`Required ID of the pod. `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-19/index.html) **200** The test delivery (`application/json`) FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-19/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-19/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/test" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [List Webhooks](/content/docs/reference/api/webhooks\#list-webhooks/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Query parameters](/content/docs/reference/api/webhooks\#query-parameters-4/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Sort oldest first. #### [Response](/content/docs/reference/api/webhooks\#response-20/index.html) **200** A page of webhooks (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `webhooks` [Webhook\[\]](/content/docs/reference/api/objects#webhook/index.html) Required Ordered by created\_at, newest first unless ascending is set. Each item of `webhooks` is a [Webhook](/content/docs/reference/api/objects#webhook/index.html): FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-20/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-20/index.html) Request ``` curl "https://api.machinemail.dev/v0/webhooks" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Create Webhook](/content/docs/reference/api/webhooks\#create-webhook/index.html) http ``` 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 ` for an endpoint that requires it). Their values are write-only: responses list only `header_names`. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_create`. #### [Request body](/content/docs/reference/api/webhooks\#request-body-6/index.html) Content type: `application/json`. FieldDescription `url``string`Required Endpoint URL: a public http(s) URL (private and loopback addresses are rejected, and re-checked before every delivery). `client_id``string` `inbox_ids``string[]` Only deliver events of these inboxes. `pod_ids``string[]` Only deliver events of these pods. `headers``Record` #### [Response](/content/docs/reference/api/webhooks\#response-21/index.html) **200** A webhook with this client\_id already exists; it is returned unchanged. (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. **201** Created (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-21/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `409` | Conflicts with an existing resource. | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-21/index.html) Request ``` 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"\ ] }' ``` Response 200 ## [Get Webhook](/content/docs/reference/api/webhooks\#get-webhook/index.html) http ``` GET /v0/webhooks/{webhook_id} ``` **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-20/index.html) FieldDescription `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-22/index.html) **200** The webhook (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-22/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-22/index.html) Request ``` curl "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Update Webhook](/content/docs/reference/api/webhooks\#update-webhook/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-21/index.html) FieldDescription `webhook_id``string`Required ID of the webhook. #### [Request body](/content/docs/reference/api/webhooks\#request-body-7/index.html) Content type: `application/json`. FieldDescription `enabled``boolean` `add_inbox_ids``string[]` Inboxes to add to inbox\_ids. `remove_inbox_ids``string[]` Inboxes to remove from inbox\_ids. `add_pod_ids``string[]` Pods to add to pod\_ids. `remove_pod_ids``string[]` Pods to remove from pod\_ids. `url``string` New endpoint URL: a public http(s) URL. `headers``Record | null` #### [Response](/content/docs/reference/api/webhooks\#response-23/index.html) **200** The updated webhook (`application/json`) FieldDescription `webhook_id``string`Required ID of the webhook. `url``string`Required URL of the webhook endpoint. Event types the webhook receives. Empty: every event type except domain.updated and trusted\_domain.\*, which are sent only when listed. `pod_ids``string[]` Only events of these pods. Absent: every pod in scope. `inbox_ids``string[]` Only events of these inboxes. Absent: every inbox in scope. `pod_id``string` Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod\_id}): it never receives events outside that pod. `inbox_id``string` Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox\_id}): it only receives events of that inbox. `secret``string`Required Signing secret (whsec\_...) for X-MachineMail-Signature. Returned on every read. `enabled``boolean`Required Whether new events are delivered. Webhooks are never disabled automatically. `updated_at``string (date-time)`Required Time at which the webhook was last updated. `created_at``string (date-time)`Required Time at which the webhook was created. `client_id``string` Client ID given at creation (idempotency key). `status``"active" | "disabled"`Required active or disabled; mirrors enabled. `header_names``string[]`Required Names of the custom delivery headers (headers), as they were set; empty when there are none. Values are write-only and never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-23/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-23/index.html) Request ``` 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" }' ``` Response 200 ## [Delete Webhook](/content/docs/reference/api/webhooks\#delete-webhook/index.html) http ``` DELETE /v0/webhooks/{webhook_id} ``` **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_delete`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-22/index.html) FieldDescription `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-24/index.html) **200** Deleted (`application/json`) FieldDescription `ok``true`Required #### [Errors](/content/docs/reference/api/webhooks\#errors-24/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-24/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "ok": true } ``` ## [List Deliveries](/content/docs/reference/api/webhooks\#list-deliveries/index.html) http ``` GET /v0/webhooks/{webhook_id}/deliveries ``` Delivery attempts of the webhook, one per event (a replay is a new delivery). **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-23/index.html) FieldDescription `webhook_id``string`Required ID of the webhook. #### [Query parameters](/content/docs/reference/api/webhooks\#query-parameters-5/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Sort oldest first. `status``"pending" | "delivered" | "failed"` Only deliveries with this status. #### [Response](/content/docs/reference/api/webhooks\#response-25/index.html) **200** A page of deliveries (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `deliveries` [WebhookDelivery\[\]](/content/docs/reference/api/objects#webhookdelivery/index.html) Required Ordered by created\_at, newest first unless ascending is set. Each item of `deliveries` is a [WebhookDelivery](/content/docs/reference/api/objects#webhookdelivery/index.html): FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-25/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-25/index.html) Request ``` curl "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Replay Delivery](/content/docs/reference/api/webhooks\#replay-delivery/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-24/index.html) FieldDescription `webhook_id``string`Required ID of the webhook. `delivery_id``string`Required ID of the delivery to replay. #### [Response](/content/docs/reference/api/webhooks\#response-26/index.html) **200** The new delivery (`application/json`) FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-26/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-26/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/deliveries/dlv_01k6x3f1ns0000j5s1vz7d0m2p/replay" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Get Webhook Headers](/content/docs/reference/api/webhooks\#get-webhook-headers/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_read`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-25/index.html) FieldDescription `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-27/index.html) **200** The header names (`application/json`) FieldDescription `header_names``string[]`Required Names of the custom delivery headers of this webhook, as they were set. Values are never returned. `headers_updated_at``string (date-time)` When the custom headers were last set or changed. Absent when they never were. #### [Errors](/content/docs/reference/api/webhooks\#errors-27/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-27/index.html) Request ``` curl "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/headers" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "header_names": ["string"], "headers_updated_at": "2026-10-01T12:00:00.000Z" } ``` ## [Update Webhook Headers](/content/docs/reference/api/webhooks\#update-webhook-headers/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-26/index.html) FieldDescription `webhook_id``string`Required ID of the webhook. #### [Request body](/content/docs/reference/api/webhooks\#request-body-8/index.html) Content type: `application/json`. FieldDescription `headers``Record` `remove_headers``string[]` Names of custom headers to remove (any case). Names that are not set are ignored. #### [Response](/content/docs/reference/api/webhooks\#response-28/index.html) **204** Updated #### [Errors](/content/docs/reference/api/webhooks\#errors-28/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-28/index.html) Request ``` 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](/content/docs/reference/api/webhooks\#send-test-event/index.html) http ``` 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 ` or the dashboard `mm_session` cookie. Permission: `webhook_update`. #### [Path parameters](/content/docs/reference/api/webhooks\#path-parameters-27/index.html) FieldDescription `webhook_id``string`Required ID of the webhook. #### [Response](/content/docs/reference/api/webhooks\#response-29/index.html) **200** The test delivery (`application/json`) FieldDescription `delivery_id``string`Required ID of the delivery (X-MachineMail-Delivery-Id). `webhook_id``string`Required ID of the webhook. `event_id``string`Required ID of the event (X-MachineMail-Event-Id). `attempt``integer`Required Number of attempts so far. `status``"pending" | "delivered" | "failed"`Required pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted. `response_status``integer` HTTP status of the last attempt. `response_body``string` First 1024 bytes of the last response body. `next_attempt_at``string (date-time)` When the next attempt is due, while pending. `last_error``string` Error of the last failed attempt (HTTP 500, a network error). `delivered_at``string (date-time)` When the delivery succeeded. `created_at``string (date-time)`Required When the delivery was queued. `updated_at``string (date-time)`Required Last change to the delivery. #### [Errors](/content/docs/reference/api/webhooks\#errors-29/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/webhooks\#example-29/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/webhooks/whk_01k6x3c2jp0000f2p8rw4a7h9k/test" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 On this page [List Webhooks in Inbox](/content/docs/reference/api/webhooks#list-webhooks-in-inbox/index.html) [Create Webhook in Inbox](/content/docs/reference/api/webhooks#create-webhook-in-inbox/index.html) [Get Webhook in Inbox](/content/docs/reference/api/webhooks#get-webhook-in-inbox/index.html) [Update Webhook in Inbox](/content/docs/reference/api/webhooks#update-webhook-in-inbox/index.html) [Delete Webhook in Inbox](/content/docs/reference/api/webhooks#delete-webhook-in-inbox/index.html) [List Deliveries in Inbox](/content/docs/reference/api/webhooks#list-deliveries-in-inbox/index.html) [Replay Delivery in Inbox](/content/docs/reference/api/webhooks#replay-delivery-in-inbox/index.html) [Get Webhook Headers in Inbox](/content/docs/reference/api/webhooks#get-webhook-headers-in-inbox/index.html) [Update Webhook Headers in Inbox](/content/docs/reference/api/webhooks#update-webhook-headers-in-inbox/index.html) [Send Test Event in Inbox](/content/docs/reference/api/webhooks#send-test-event-in-inbox/index.html) [List Webhooks in Pod](/content/docs/reference/api/webhooks#list-webhooks-in-pod/index.html) [Create Webhook in Pod](/content/docs/reference/api/webhooks#create-webhook-in-pod/index.html) [Get Webhook in Pod](/content/docs/reference/api/webhooks#get-webhook-in-pod/index.html) [Update Webhook in Pod](/content/docs/reference/api/webhooks#update-webhook-in-pod/index.html) [Delete Webhook in Pod](/content/docs/reference/api/webhooks#delete-webhook-in-pod/index.html) [List Deliveries in Pod](/content/docs/reference/api/webhooks#list-deliveries-in-pod/index.html) [Replay Delivery in Pod](/content/docs/reference/api/webhooks#replay-delivery-in-pod/index.html) [Get Webhook Headers in Pod](/content/docs/reference/api/webhooks#get-webhook-headers-in-pod/index.html) [Update Webhook Headers in Pod](/content/docs/reference/api/webhooks#update-webhook-headers-in-pod/index.html) [Send Test Event in Pod](/content/docs/reference/api/webhooks#send-test-event-in-pod/index.html) [List Webhooks](/content/docs/reference/api/webhooks#list-webhooks/index.html) [Create Webhook](/content/docs/reference/api/webhooks#create-webhook/index.html) [Get Webhook](/content/docs/reference/api/webhooks#get-webhook/index.html) [Update Webhook](/content/docs/reference/api/webhooks#update-webhook/index.html) [Delete Webhook](/content/docs/reference/api/webhooks#delete-webhook/index.html) [List Deliveries](/content/docs/reference/api/webhooks#list-deliveries/index.html) [Replay Delivery](/content/docs/reference/api/webhooks#replay-delivery/index.html) [Get Webhook Headers](/content/docs/reference/api/webhooks#get-webhook-headers/index.html) [Update Webhook Headers](/content/docs/reference/api/webhooks#update-webhook-headers/index.html) [Send Test Event](/content/docs/reference/api/webhooks#send-test-event/index.html) 100% readTop