---
title: "Keys and webhooks"
description: "The credentials and endpoints this workspace has issued."
url: "https://nextmail.sh/docs/mcp/tools/keys"
area: "MCP server"
category: "Tools"
---

# Keys and webhooks

The credentials and endpoints this workspace has issued.

## Keys and webhooks tools

| Tool | What it does |
| --- | --- |
| listApiKeys | Every API key this workspace has issued, what it may do and what it may send as, in a masked form that is enough to tell two keys apart and nothing more. Returned a page at a time. |
| listWebhooks | Every webhook endpoint this workspace has, where it posts, whether it is enabled and which events it asked for. Signing secrets are never shown. Returned a page at a time. |
| listWebhookEvents | Every event an endpoint can subscribe to, grouped by family, with a line saying when each one fires. |
| listApiKeyRequests | The request log of the workspace’s keys, newest first: method, path, status, error code, duration, IP and user agent. Narrow it to one key, to failed calls, to exact status codes, to one route, or to a window. Returned a page at a time. |
| listApiKeyActivity | What happened to the keys, newest first: created, updated, rotated, switched off or on, revoked, deleted and refused, and who did it. Returned a page at a time. |
| listWebhookDeliveries | The delivery log of one endpoint or of all of them, newest first, narrowed to delivered or failed and to a window. Returned a page at a time. |
| getWebhookDelivery | One delivery in full: the body that was sent, what the receiver answered, every try of the event, and whether a replay would be accepted. |
| replayWebhookDelivery | Send one event again, now, with its original id and a fresh signature. It always asks before it runs. |
| listWebhookActivity | What happened to the webhooks, newest first: created, changed, switched off or on, secret rotated, tested, replayed and removed, and who did it. Returned a page at a time. |
| getWebhook | One webhook endpoint: where it posts, whether it is on, which events it wants and which addresses it hears about. |
| createWebhook | Add a webhook endpoint with the events it wants and, if you like, allowlists. The signing secret is shown once. |
| updateWebhook | Change an endpoint’s URL, events, description or allowlists, or switch it on or off. |
| deleteWebhook | Remove a webhook endpoint. Its log and history stay. A chat always asks first. |
| rotateWebhookSecret | Give an endpoint a new signing secret, shown once. The old one keeps signing beside it for 24 hours. |
| testWebhook | Post one signed test event to an endpoint now and report what it answered. A chat always asks first. |
| getWebhookStats | How the deliveries went inside a window: attempts, delivered and failed, a series, the events sent and the response codes. |
| getApiKeyStats | What the keys did inside a window: the mail they sent, refused calls, requests and failures, the routes called most and the status codes. |

> A secret is shown once, when a key or a webhook endpoint is made or its secret is rotated, and nothing recovers it afterwards. `createWebhook` and `rotateWebhookSecret` are the tools here that return one. After a rotation the old webhook secret keeps signing for 24 hours, so hand the receiver the new one within the day. The assistant in the app does not rotate secrets.

> Keys are only read here. Rotating a key, switching it off, revoking it and changing what it may do need a permission no app is ever given, so they happen in Settings → API keys and with `/keys` on the REST API, where switching a key off is the reversible step and revoking it the permanent one.

> There is no createApiKey here: issuing a key from inside a chat window is a quiet, wide change nobody sees afterwards, so keys are made in Settings and with `POST /keys`. The webhook tools act exactly as `/webhooks` on the REST API does, and need the owner or someone whose role reaches every address, through an app that reaches every address.

> The key list and logs answer for the owner, or someone whose role holds `api-keys:read` and reaches every address, and the webhook logs and deliveries for the owner or someone whose role reaches every address, in both cases through an app that reaches every address, because a delivery body names the addresses the event is about. `replayWebhookDelivery` reaches a real receiver, so the assistant in the app always shows a card to approve it and a client should ask first as well. It is refused with `retry_in_flight` while an automatic retry of the event is being sent and with `replay_in_flight` while another replay of it is.

> Some tools on this server make a change the REST API guards with a verification code, and ask for the same code. Until the client has verified a code in the last 60 minutes, or the person has chosen Allow changes for 60 minutes on it in Account → Connected apps, such a tool answers with a result that starts `Refused (step_up_required):` and changes nothing. `emptyAudience` never asks for a code. The API Authentication page lists every tool that asks, and shows how to ask for a code and verify it.

## Reference

### `listApiKeys`

Every API key this workspace has issued, what it may do and what it may send as. The secret is shown once, when the key is made or rotated, and nothing recovers it afterwards, so what you get here is a masked form that is enough to tell two keys apart and nothing more. Send scope is the line worth reading: a key with no scope set may send as any address the workspace owns, and a key that names domains or addresses also reads only the sent mail, tracking and calendar of that same set. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `api-keys:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /keys`](https://nextmail.sh/docs/api/reference/api-keys#get-keys), [`GET /keys/{id}`](https://nextmail.sh/docs/api/reference/api-keys#get-keys-id); TypeScript [`nextmail.keys.list()`](https://nextmail.sh/docs/sdk/reference/keys#list), [`nextmail.keys.listAll()`](https://nextmail.sh/docs/sdk/reference/keys#listAll), [`nextmail.keys.iterate()`](https://nextmail.sh/docs/sdk/reference/keys#iterate), [`nextmail.keys.get()`](https://nextmail.sh/docs/sdk/reference/keys#get); Python [`keys.list()`](https://nextmail.sh/docs/python/reference/keys#list), [`keys.list_all()`](https://nextmail.sh/docs/python/reference/keys#listAll), [`keys.iterate()`](https://nextmail.sh/docs/python/reference/keys#iterate), [`keys.get()`](https://nextmail.sh/docs/python/reference/keys#get); Ruby [`keys.list`](https://nextmail.sh/docs/ruby/reference/keys#list), [`keys.list_all`](https://nextmail.sh/docs/ruby/reference/keys#listAll), [`keys.iterate`](https://nextmail.sh/docs/ruby/reference/keys#iterate), [`keys.get`](https://nextmail.sh/docs/ruby/reference/keys#get); PHP [`keys->list`](https://nextmail.sh/docs/php/reference/keys#list), [`keys->listAll`](https://nextmail.sh/docs/php/reference/keys#listAll), [`keys->iterate`](https://nextmail.sh/docs/php/reference/keys#iterate), [`keys->get`](https://nextmail.sh/docs/php/reference/keys#get); Go [`Keys.List`](https://nextmail.sh/docs/go/reference/keys#list), [`Keys.ListAll`](https://nextmail.sh/docs/go/reference/keys#listAll), [`Keys.Iterate`](https://nextmail.sh/docs/go/reference/keys#iterate), [`Keys.Get`](https://nextmail.sh/docs/go/reference/keys#get); Java [`keys().list`](https://nextmail.sh/docs/java/reference/keys#list), [`keys().listAll`](https://nextmail.sh/docs/java/reference/keys#listAll), [`keys().iterate`](https://nextmail.sh/docs/java/reference/keys#iterate), [`keys().get`](https://nextmail.sh/docs/java/reference/keys#get); C# [`Keys.ListAsync`](https://nextmail.sh/docs/csharp/reference/keys#list), [`Keys.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/keys#listAll), [`Keys.IterateAsync`](https://nextmail.sh/docs/csharp/reference/keys#iterate), [`Keys.GetAsync`](https://nextmail.sh/docs/csharp/reference/keys#get).

### `listWebhooks`

Every webhook endpoint this workspace has, where it posts, whether it is enabled, which events it asked for and which addresses it hears about. An endpoint with no events listed receives every email event except email.replied, and one that names no addresses hears about every address this workspace owns. A delivery is tried up to 8 times over about 27 and a half hours before it is given up on, and a delivery that still failed can be replayed, one event at a time, from Settings or the API. An endpoint whose deliveries have all failed a hundred events in a row is disabled automatically, with the reason and the time shown here. Signing secrets are never shown. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `webhooks:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /webhooks`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks), [`GET /webhooks/{id}`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-id); TypeScript [`nextmail.webhooks.list()`](https://nextmail.sh/docs/sdk/reference/webhooks#list), [`nextmail.webhooks.listAll()`](https://nextmail.sh/docs/sdk/reference/webhooks#listAll), [`nextmail.webhooks.iterate()`](https://nextmail.sh/docs/sdk/reference/webhooks#iterate), [`nextmail.webhooks.get()`](https://nextmail.sh/docs/sdk/reference/webhooks#get); Python [`webhooks.list()`](https://nextmail.sh/docs/python/reference/webhooks#list), [`webhooks.list_all()`](https://nextmail.sh/docs/python/reference/webhooks#listAll), [`webhooks.iterate()`](https://nextmail.sh/docs/python/reference/webhooks#iterate), [`webhooks.get()`](https://nextmail.sh/docs/python/reference/webhooks#get); Ruby [`webhooks.list`](https://nextmail.sh/docs/ruby/reference/webhooks#list), [`webhooks.list_all`](https://nextmail.sh/docs/ruby/reference/webhooks#listAll), [`webhooks.iterate`](https://nextmail.sh/docs/ruby/reference/webhooks#iterate), [`webhooks.get`](https://nextmail.sh/docs/ruby/reference/webhooks#get); PHP [`webhooks->list`](https://nextmail.sh/docs/php/reference/webhooks#list), [`webhooks->listAll`](https://nextmail.sh/docs/php/reference/webhooks#listAll), [`webhooks->iterate`](https://nextmail.sh/docs/php/reference/webhooks#iterate), [`webhooks->get`](https://nextmail.sh/docs/php/reference/webhooks#get); Go [`Webhooks.List`](https://nextmail.sh/docs/go/reference/webhooks#list), [`Webhooks.ListAll`](https://nextmail.sh/docs/go/reference/webhooks#listAll), [`Webhooks.Iterate`](https://nextmail.sh/docs/go/reference/webhooks#iterate), [`Webhooks.Get`](https://nextmail.sh/docs/go/reference/webhooks#get); Java [`webhooks().list`](https://nextmail.sh/docs/java/reference/webhooks#list), [`webhooks().listAll`](https://nextmail.sh/docs/java/reference/webhooks#listAll), [`webhooks().iterate`](https://nextmail.sh/docs/java/reference/webhooks#iterate), [`webhooks().get`](https://nextmail.sh/docs/java/reference/webhooks#get); C# [`Webhooks.ListAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#list), [`Webhooks.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listAll), [`Webhooks.IterateAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#iterate), [`Webhooks.GetAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#get).

### `listWebhookEvents`

Every event an endpoint in this workspace can subscribe to, with a line saying when each one fires. Events are grouped by family: email events describe one message, domain events describe a domain changing state, and suppression events describe the list of addresses this workspace may no longer send to. An endpoint that names no events receives every email event except email.replied, so email.replied and the domain and suppression families only reach an endpoint that asks for them by name.

- Scopes: `webhooks:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

Takes no input.

Also available in: API [`GET /webhooks/events`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-events); TypeScript [`nextmail.webhooks.listEvents()`](https://nextmail.sh/docs/sdk/reference/webhooks#listEvents); Python [`webhooks.list_events()`](https://nextmail.sh/docs/python/reference/webhooks#listEvents); Ruby [`webhooks.list_events`](https://nextmail.sh/docs/ruby/reference/webhooks#listEvents); PHP [`webhooks->listEvents`](https://nextmail.sh/docs/php/reference/webhooks#listEvents); Go [`Webhooks.ListEvents`](https://nextmail.sh/docs/go/reference/webhooks#listEvents); Java [`webhooks().listEvents`](https://nextmail.sh/docs/java/reference/webhooks#listEvents); C# [`Webhooks.ListEventsAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listEvents).

### `listApiKeyRequests`

The request log of the API keys in this workspace, newest first: every authenticated REST call a key made, with its method, path, status, error code, duration, IP and user agent. Never a body or a query string. Nothing is pruned, so the log reaches back to the first call. Narrow it to one key with keyId, to failed calls (status 400 and up) with failedOnly, to exact status codes with statuses, to one route with path, and to a window with since and until. The filters combine. path matches the route rather than the exact path: ids and addresses in it count as :id and :address, so /emails/:id reads every call to one email, and a path ending in * reads every route that starts with it. Calls made with an OAuth access token are not in it. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `api-keys:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `keyId` (`string`, not empty)
- `failedOnly` (`boolean`)
- `statuses` (`integer[]`, up to 20 items): Only calls answered with one of these HTTP status codes, such as [401, 403].
- `path` (`string`): Only calls to this route, such as /emails or /emails/:id. End it with * to match every route that starts with it, such as /emails/*.
- `since` (`string`): Only rows at or after this ISO 8601 instant, such as 2026-09-01T00:00:00Z.
- `until` (`string`): Only rows before this ISO 8601 instant.
- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /keys/requests`](https://nextmail.sh/docs/api/reference/api-keys#get-keys-requests), [`GET /keys/{id}/requests`](https://nextmail.sh/docs/api/reference/api-keys#get-keys-id-requests); TypeScript [`nextmail.keys.listWorkspaceRequests()`](https://nextmail.sh/docs/sdk/reference/keys#listWorkspaceRequests), [`nextmail.keys.listAllWorkspaceRequests()`](https://nextmail.sh/docs/sdk/reference/keys#listAllWorkspaceRequests), [`nextmail.keys.iterateWorkspaceRequests()`](https://nextmail.sh/docs/sdk/reference/keys#iterateWorkspaceRequests), [`nextmail.keys.listRequests()`](https://nextmail.sh/docs/sdk/reference/keys#listRequests), [`nextmail.keys.listAllRequests()`](https://nextmail.sh/docs/sdk/reference/keys#listAllRequests), [`nextmail.keys.iterateRequests()`](https://nextmail.sh/docs/sdk/reference/keys#iterateRequests); Python [`keys.list_workspace_requests()`](https://nextmail.sh/docs/python/reference/keys#listWorkspaceRequests), [`keys.list_all_workspace_requests()`](https://nextmail.sh/docs/python/reference/keys#listAllWorkspaceRequests), [`keys.iterate_workspace_requests()`](https://nextmail.sh/docs/python/reference/keys#iterateWorkspaceRequests), [`keys.list_requests()`](https://nextmail.sh/docs/python/reference/keys#listRequests), [`keys.list_all_requests()`](https://nextmail.sh/docs/python/reference/keys#listAllRequests), [`keys.iterate_requests()`](https://nextmail.sh/docs/python/reference/keys#iterateRequests); Ruby [`keys.list_workspace_requests`](https://nextmail.sh/docs/ruby/reference/keys#listWorkspaceRequests), [`keys.list_all_workspace_requests`](https://nextmail.sh/docs/ruby/reference/keys#listAllWorkspaceRequests), [`keys.iterate_workspace_requests`](https://nextmail.sh/docs/ruby/reference/keys#iterateWorkspaceRequests), [`keys.list_requests`](https://nextmail.sh/docs/ruby/reference/keys#listRequests), [`keys.list_all_requests`](https://nextmail.sh/docs/ruby/reference/keys#listAllRequests), [`keys.iterate_requests`](https://nextmail.sh/docs/ruby/reference/keys#iterateRequests); PHP [`keys->listWorkspaceRequests`](https://nextmail.sh/docs/php/reference/keys#listWorkspaceRequests), [`keys->listAllWorkspaceRequests`](https://nextmail.sh/docs/php/reference/keys#listAllWorkspaceRequests), [`keys->iterateWorkspaceRequests`](https://nextmail.sh/docs/php/reference/keys#iterateWorkspaceRequests), [`keys->listRequests`](https://nextmail.sh/docs/php/reference/keys#listRequests), [`keys->listAllRequests`](https://nextmail.sh/docs/php/reference/keys#listAllRequests), [`keys->iterateRequests`](https://nextmail.sh/docs/php/reference/keys#iterateRequests); Go [`Keys.ListWorkspaceRequests`](https://nextmail.sh/docs/go/reference/keys#listWorkspaceRequests), [`Keys.ListAllWorkspaceRequests`](https://nextmail.sh/docs/go/reference/keys#listAllWorkspaceRequests), [`Keys.IterateWorkspaceRequests`](https://nextmail.sh/docs/go/reference/keys#iterateWorkspaceRequests), [`Keys.ListRequests`](https://nextmail.sh/docs/go/reference/keys#listRequests), [`Keys.ListAllRequests`](https://nextmail.sh/docs/go/reference/keys#listAllRequests), [`Keys.IterateRequests`](https://nextmail.sh/docs/go/reference/keys#iterateRequests); Java [`keys().listWorkspaceRequests`](https://nextmail.sh/docs/java/reference/keys#listWorkspaceRequests), [`keys().listAllWorkspaceRequests`](https://nextmail.sh/docs/java/reference/keys#listAllWorkspaceRequests), [`keys().iterateWorkspaceRequests`](https://nextmail.sh/docs/java/reference/keys#iterateWorkspaceRequests), [`keys().listRequests`](https://nextmail.sh/docs/java/reference/keys#listRequests), [`keys().listAllRequests`](https://nextmail.sh/docs/java/reference/keys#listAllRequests), [`keys().iterateRequests`](https://nextmail.sh/docs/java/reference/keys#iterateRequests); C# [`Keys.ListWorkspaceRequestsAsync`](https://nextmail.sh/docs/csharp/reference/keys#listWorkspaceRequests), [`Keys.ListAllWorkspaceRequestsAsync`](https://nextmail.sh/docs/csharp/reference/keys#listAllWorkspaceRequests), [`Keys.IterateWorkspaceRequestsAsync`](https://nextmail.sh/docs/csharp/reference/keys#iterateWorkspaceRequests), [`Keys.ListRequestsAsync`](https://nextmail.sh/docs/csharp/reference/keys#listRequests), [`Keys.ListAllRequestsAsync`](https://nextmail.sh/docs/csharp/reference/keys#listAllRequests), [`Keys.IterateRequestsAsync`](https://nextmail.sh/docs/csharp/reference/keys#iterateRequests).

### `listApiKeyActivity`

What happened TO the API keys in this workspace, newest first: created, updated, rotated, switched off or on, revoked, deleted, and every refused attempt to authenticate with one. Each row says who did it, a person as @username or a key as "API key <name>", and what changed. Narrow it with keyId, since and until. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `api-keys:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `keyId` (`string`, not empty)
- `since` (`string`): Only rows at or after this ISO 8601 instant, such as 2026-09-01T00:00:00Z.
- `until` (`string`): Only rows before this ISO 8601 instant.
- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /keys/activity`](https://nextmail.sh/docs/api/reference/api-keys#get-keys-activity), [`GET /keys/{id}/activity`](https://nextmail.sh/docs/api/reference/api-keys#get-keys-id-activity); TypeScript [`nextmail.keys.listWorkspaceActivity()`](https://nextmail.sh/docs/sdk/reference/keys#listWorkspaceActivity), [`nextmail.keys.listAllWorkspaceActivity()`](https://nextmail.sh/docs/sdk/reference/keys#listAllWorkspaceActivity), [`nextmail.keys.iterateWorkspaceActivity()`](https://nextmail.sh/docs/sdk/reference/keys#iterateWorkspaceActivity), [`nextmail.keys.listActivity()`](https://nextmail.sh/docs/sdk/reference/keys#listActivity), [`nextmail.keys.listAllActivity()`](https://nextmail.sh/docs/sdk/reference/keys#listAllActivity), [`nextmail.keys.iterateActivity()`](https://nextmail.sh/docs/sdk/reference/keys#iterateActivity); Python [`keys.list_workspace_activity()`](https://nextmail.sh/docs/python/reference/keys#listWorkspaceActivity), [`keys.list_all_workspace_activity()`](https://nextmail.sh/docs/python/reference/keys#listAllWorkspaceActivity), [`keys.iterate_workspace_activity()`](https://nextmail.sh/docs/python/reference/keys#iterateWorkspaceActivity), [`keys.list_activity()`](https://nextmail.sh/docs/python/reference/keys#listActivity), [`keys.list_all_activity()`](https://nextmail.sh/docs/python/reference/keys#listAllActivity), [`keys.iterate_activity()`](https://nextmail.sh/docs/python/reference/keys#iterateActivity); Ruby [`keys.list_workspace_activity`](https://nextmail.sh/docs/ruby/reference/keys#listWorkspaceActivity), [`keys.list_all_workspace_activity`](https://nextmail.sh/docs/ruby/reference/keys#listAllWorkspaceActivity), [`keys.iterate_workspace_activity`](https://nextmail.sh/docs/ruby/reference/keys#iterateWorkspaceActivity), [`keys.list_activity`](https://nextmail.sh/docs/ruby/reference/keys#listActivity), [`keys.list_all_activity`](https://nextmail.sh/docs/ruby/reference/keys#listAllActivity), [`keys.iterate_activity`](https://nextmail.sh/docs/ruby/reference/keys#iterateActivity); PHP [`keys->listWorkspaceActivity`](https://nextmail.sh/docs/php/reference/keys#listWorkspaceActivity), [`keys->listAllWorkspaceActivity`](https://nextmail.sh/docs/php/reference/keys#listAllWorkspaceActivity), [`keys->iterateWorkspaceActivity`](https://nextmail.sh/docs/php/reference/keys#iterateWorkspaceActivity), [`keys->listActivity`](https://nextmail.sh/docs/php/reference/keys#listActivity), [`keys->listAllActivity`](https://nextmail.sh/docs/php/reference/keys#listAllActivity), [`keys->iterateActivity`](https://nextmail.sh/docs/php/reference/keys#iterateActivity); Go [`Keys.ListWorkspaceActivity`](https://nextmail.sh/docs/go/reference/keys#listWorkspaceActivity), [`Keys.ListAllWorkspaceActivity`](https://nextmail.sh/docs/go/reference/keys#listAllWorkspaceActivity), [`Keys.IterateWorkspaceActivity`](https://nextmail.sh/docs/go/reference/keys#iterateWorkspaceActivity), [`Keys.ListActivity`](https://nextmail.sh/docs/go/reference/keys#listActivity), [`Keys.ListAllActivity`](https://nextmail.sh/docs/go/reference/keys#listAllActivity), [`Keys.IterateActivity`](https://nextmail.sh/docs/go/reference/keys#iterateActivity); Java [`keys().listWorkspaceActivity`](https://nextmail.sh/docs/java/reference/keys#listWorkspaceActivity), [`keys().listAllWorkspaceActivity`](https://nextmail.sh/docs/java/reference/keys#listAllWorkspaceActivity), [`keys().iterateWorkspaceActivity`](https://nextmail.sh/docs/java/reference/keys#iterateWorkspaceActivity), [`keys().listActivity`](https://nextmail.sh/docs/java/reference/keys#listActivity), [`keys().listAllActivity`](https://nextmail.sh/docs/java/reference/keys#listAllActivity), [`keys().iterateActivity`](https://nextmail.sh/docs/java/reference/keys#iterateActivity); C# [`Keys.ListWorkspaceActivityAsync`](https://nextmail.sh/docs/csharp/reference/keys#listWorkspaceActivity), [`Keys.ListAllWorkspaceActivityAsync`](https://nextmail.sh/docs/csharp/reference/keys#listAllWorkspaceActivity), [`Keys.IterateWorkspaceActivityAsync`](https://nextmail.sh/docs/csharp/reference/keys#iterateWorkspaceActivity), [`Keys.ListActivityAsync`](https://nextmail.sh/docs/csharp/reference/keys#listActivity), [`Keys.ListAllActivityAsync`](https://nextmail.sh/docs/csharp/reference/keys#listAllActivity), [`Keys.IterateActivityAsync`](https://nextmail.sh/docs/csharp/reference/keys#iterateActivity).

### `listWebhookDeliveries`

The delivery log of this workspace’s webhooks, newest first: one row per POST, with the event, the answer the receiver gave, how long it took, which try it was and when the next automatic retry is due. Nothing is pruned, so it reaches the first delivery. Leave endpointId out to read every endpoint at once. status narrows to delivered or failed, and since and until to a window. The body that was sent is not here; getWebhookDelivery reads it. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `webhooks:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `endpointId` (`string`, not empty)
- `status` (`string`, one of `"delivered"`, `"failed"`)
- `since` (`string`): Only rows at or after this ISO 8601 instant, such as 2026-09-01T00:00:00Z.
- `until` (`string`): Only rows before this ISO 8601 instant.
- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /webhooks/deliveries`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-deliveries), [`GET /webhooks/{id}/deliveries`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-id-deliveries); TypeScript [`nextmail.webhooks.listWorkspaceDeliveries()`](https://nextmail.sh/docs/sdk/reference/webhooks#listWorkspaceDeliveries), [`nextmail.webhooks.listAllWorkspaceDeliveries()`](https://nextmail.sh/docs/sdk/reference/webhooks#listAllWorkspaceDeliveries), [`nextmail.webhooks.iterateWorkspaceDeliveries()`](https://nextmail.sh/docs/sdk/reference/webhooks#iterateWorkspaceDeliveries), [`nextmail.webhooks.listDeliveries()`](https://nextmail.sh/docs/sdk/reference/webhooks#listDeliveries), [`nextmail.webhooks.listAllDeliveries()`](https://nextmail.sh/docs/sdk/reference/webhooks#listAllDeliveries), [`nextmail.webhooks.iterateDeliveries()`](https://nextmail.sh/docs/sdk/reference/webhooks#iterateDeliveries); Python [`webhooks.list_workspace_deliveries()`](https://nextmail.sh/docs/python/reference/webhooks#listWorkspaceDeliveries), [`webhooks.list_all_workspace_deliveries()`](https://nextmail.sh/docs/python/reference/webhooks#listAllWorkspaceDeliveries), [`webhooks.iterate_workspace_deliveries()`](https://nextmail.sh/docs/python/reference/webhooks#iterateWorkspaceDeliveries), [`webhooks.list_deliveries()`](https://nextmail.sh/docs/python/reference/webhooks#listDeliveries), [`webhooks.list_all_deliveries()`](https://nextmail.sh/docs/python/reference/webhooks#listAllDeliveries), [`webhooks.iterate_deliveries()`](https://nextmail.sh/docs/python/reference/webhooks#iterateDeliveries); Ruby [`webhooks.list_workspace_deliveries`](https://nextmail.sh/docs/ruby/reference/webhooks#listWorkspaceDeliveries), [`webhooks.list_all_workspace_deliveries`](https://nextmail.sh/docs/ruby/reference/webhooks#listAllWorkspaceDeliveries), [`webhooks.iterate_workspace_deliveries`](https://nextmail.sh/docs/ruby/reference/webhooks#iterateWorkspaceDeliveries), [`webhooks.list_deliveries`](https://nextmail.sh/docs/ruby/reference/webhooks#listDeliveries), [`webhooks.list_all_deliveries`](https://nextmail.sh/docs/ruby/reference/webhooks#listAllDeliveries), [`webhooks.iterate_deliveries`](https://nextmail.sh/docs/ruby/reference/webhooks#iterateDeliveries); PHP [`webhooks->listWorkspaceDeliveries`](https://nextmail.sh/docs/php/reference/webhooks#listWorkspaceDeliveries), [`webhooks->listAllWorkspaceDeliveries`](https://nextmail.sh/docs/php/reference/webhooks#listAllWorkspaceDeliveries), [`webhooks->iterateWorkspaceDeliveries`](https://nextmail.sh/docs/php/reference/webhooks#iterateWorkspaceDeliveries), [`webhooks->listDeliveries`](https://nextmail.sh/docs/php/reference/webhooks#listDeliveries), [`webhooks->listAllDeliveries`](https://nextmail.sh/docs/php/reference/webhooks#listAllDeliveries), [`webhooks->iterateDeliveries`](https://nextmail.sh/docs/php/reference/webhooks#iterateDeliveries); Go [`Webhooks.ListWorkspaceDeliveries`](https://nextmail.sh/docs/go/reference/webhooks#listWorkspaceDeliveries), [`Webhooks.ListAllWorkspaceDeliveries`](https://nextmail.sh/docs/go/reference/webhooks#listAllWorkspaceDeliveries), [`Webhooks.IterateWorkspaceDeliveries`](https://nextmail.sh/docs/go/reference/webhooks#iterateWorkspaceDeliveries), [`Webhooks.ListDeliveries`](https://nextmail.sh/docs/go/reference/webhooks#listDeliveries), [`Webhooks.ListAllDeliveries`](https://nextmail.sh/docs/go/reference/webhooks#listAllDeliveries), [`Webhooks.IterateDeliveries`](https://nextmail.sh/docs/go/reference/webhooks#iterateDeliveries); Java [`webhooks().listWorkspaceDeliveries`](https://nextmail.sh/docs/java/reference/webhooks#listWorkspaceDeliveries), [`webhooks().listAllWorkspaceDeliveries`](https://nextmail.sh/docs/java/reference/webhooks#listAllWorkspaceDeliveries), [`webhooks().iterateWorkspaceDeliveries`](https://nextmail.sh/docs/java/reference/webhooks#iterateWorkspaceDeliveries), [`webhooks().listDeliveries`](https://nextmail.sh/docs/java/reference/webhooks#listDeliveries), [`webhooks().listAllDeliveries`](https://nextmail.sh/docs/java/reference/webhooks#listAllDeliveries), [`webhooks().iterateDeliveries`](https://nextmail.sh/docs/java/reference/webhooks#iterateDeliveries); C# [`Webhooks.ListWorkspaceDeliveriesAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listWorkspaceDeliveries), [`Webhooks.ListAllWorkspaceDeliveriesAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listAllWorkspaceDeliveries), [`Webhooks.IterateWorkspaceDeliveriesAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#iterateWorkspaceDeliveries), [`Webhooks.ListDeliveriesAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listDeliveries), [`Webhooks.ListAllDeliveriesAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listAllDeliveries), [`Webhooks.IterateDeliveriesAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#iterateDeliveries).

### `getWebhookDelivery`

One webhook delivery in full: the exact JSON body that was POSTed, the first 2,000 characters the receiver answered, every try of the same event on that endpoint, when the next automatic retry is due, and whether replayWebhookDelivery would send it again (and if not, why). The body names the addresses the event is about, so only the owner of the workspace, or someone whose role reaches every address, can read it, through an app that reaches every address.

- Scopes: `webhooks:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `deliveryId` (`string`, required, 1 to 64 characters)

Also available in: API [`GET /webhooks/{id}/deliveries/{deliveryId}`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-id-deliveries-deliveryid); TypeScript [`nextmail.webhooks.getDelivery()`](https://nextmail.sh/docs/sdk/reference/webhooks#getDelivery); Python [`webhooks.get_delivery()`](https://nextmail.sh/docs/python/reference/webhooks#getDelivery); Ruby [`webhooks.get_delivery`](https://nextmail.sh/docs/ruby/reference/webhooks#getDelivery); PHP [`webhooks->getDelivery`](https://nextmail.sh/docs/php/reference/webhooks#getDelivery); Go [`Webhooks.GetDelivery`](https://nextmail.sh/docs/go/reference/webhooks#getDelivery); Java [`webhooks().getDelivery`](https://nextmail.sh/docs/java/reference/webhooks#getDelivery); C# [`Webhooks.GetDeliveryAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#getDelivery).

### `replayWebhookDelivery`

Send one webhook event again, now, with its original id, type, createdAt and data, and a fresh signature. It reaches a real receiver, so confirm with the person before calling it, every time. One event per call; there is no way to replay everything that failed. It is refused with retry_in_flight while an automatic retry of the same event is being sent, with replay_in_flight while another replay of it is, and when the endpoint is switched off, no longer listens for the event, no longer covers its address, or the delivery has no stored body. Only the owner of the workspace, or someone whose role reaches every address, can replay, through an app that reaches every address.

- Scopes: `webhooks:write`.
- The app's assistant always asks first.
- Toolkit: `workspace`.

**Inputs**

- `deliveryId` (`string`, required, 1 to 64 characters)

Also available in: API [`POST /webhooks/{id}/deliveries/{deliveryId}/replay`](https://nextmail.sh/docs/api/reference/webhooks#post-webhooks-id-deliveries-deliveryid-replay); TypeScript [`nextmail.webhooks.replayDelivery()`](https://nextmail.sh/docs/sdk/reference/webhooks#replayDelivery); Python [`webhooks.replay_delivery()`](https://nextmail.sh/docs/python/reference/webhooks#replayDelivery); Ruby [`webhooks.replay_delivery`](https://nextmail.sh/docs/ruby/reference/webhooks#replayDelivery); PHP [`webhooks->replayDelivery`](https://nextmail.sh/docs/php/reference/webhooks#replayDelivery); Go [`Webhooks.ReplayDelivery`](https://nextmail.sh/docs/go/reference/webhooks#replayDelivery); Java [`webhooks().replayDelivery`](https://nextmail.sh/docs/java/reference/webhooks#replayDelivery); C# [`Webhooks.ReplayDeliveryAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#replayDelivery).

### `listWebhookActivity`

What happened TO this workspace’s webhooks, newest first: created, updated, switched on or off (by a person or automatically after repeated failures), secret rotated, tested, replayed and removed. Each row says who did it, a person as @username or a key as "API key <name>", and what changed. A removed webhook keeps its history. Narrow it with endpointId, since and until. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `webhooks:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `endpointId` (`string`, not empty)
- `since` (`string`): Only rows at or after this ISO 8601 instant, such as 2026-09-01T00:00:00Z.
- `until` (`string`): Only rows before this ISO 8601 instant.
- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /webhooks/activity`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-activity), [`GET /webhooks/{id}/activity`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-id-activity); TypeScript [`nextmail.webhooks.listWorkspaceActivity()`](https://nextmail.sh/docs/sdk/reference/webhooks#listWorkspaceActivity), [`nextmail.webhooks.listAllWorkspaceActivity()`](https://nextmail.sh/docs/sdk/reference/webhooks#listAllWorkspaceActivity), [`nextmail.webhooks.iterateWorkspaceActivity()`](https://nextmail.sh/docs/sdk/reference/webhooks#iterateWorkspaceActivity), [`nextmail.webhooks.listActivity()`](https://nextmail.sh/docs/sdk/reference/webhooks#listActivity), [`nextmail.webhooks.listAllActivity()`](https://nextmail.sh/docs/sdk/reference/webhooks#listAllActivity), [`nextmail.webhooks.iterateActivity()`](https://nextmail.sh/docs/sdk/reference/webhooks#iterateActivity); Python [`webhooks.list_workspace_activity()`](https://nextmail.sh/docs/python/reference/webhooks#listWorkspaceActivity), [`webhooks.list_all_workspace_activity()`](https://nextmail.sh/docs/python/reference/webhooks#listAllWorkspaceActivity), [`webhooks.iterate_workspace_activity()`](https://nextmail.sh/docs/python/reference/webhooks#iterateWorkspaceActivity), [`webhooks.list_activity()`](https://nextmail.sh/docs/python/reference/webhooks#listActivity), [`webhooks.list_all_activity()`](https://nextmail.sh/docs/python/reference/webhooks#listAllActivity), [`webhooks.iterate_activity()`](https://nextmail.sh/docs/python/reference/webhooks#iterateActivity); Ruby [`webhooks.list_workspace_activity`](https://nextmail.sh/docs/ruby/reference/webhooks#listWorkspaceActivity), [`webhooks.list_all_workspace_activity`](https://nextmail.sh/docs/ruby/reference/webhooks#listAllWorkspaceActivity), [`webhooks.iterate_workspace_activity`](https://nextmail.sh/docs/ruby/reference/webhooks#iterateWorkspaceActivity), [`webhooks.list_activity`](https://nextmail.sh/docs/ruby/reference/webhooks#listActivity), [`webhooks.list_all_activity`](https://nextmail.sh/docs/ruby/reference/webhooks#listAllActivity), [`webhooks.iterate_activity`](https://nextmail.sh/docs/ruby/reference/webhooks#iterateActivity); PHP [`webhooks->listWorkspaceActivity`](https://nextmail.sh/docs/php/reference/webhooks#listWorkspaceActivity), [`webhooks->listAllWorkspaceActivity`](https://nextmail.sh/docs/php/reference/webhooks#listAllWorkspaceActivity), [`webhooks->iterateWorkspaceActivity`](https://nextmail.sh/docs/php/reference/webhooks#iterateWorkspaceActivity), [`webhooks->listActivity`](https://nextmail.sh/docs/php/reference/webhooks#listActivity), [`webhooks->listAllActivity`](https://nextmail.sh/docs/php/reference/webhooks#listAllActivity), [`webhooks->iterateActivity`](https://nextmail.sh/docs/php/reference/webhooks#iterateActivity); Go [`Webhooks.ListWorkspaceActivity`](https://nextmail.sh/docs/go/reference/webhooks#listWorkspaceActivity), [`Webhooks.ListAllWorkspaceActivity`](https://nextmail.sh/docs/go/reference/webhooks#listAllWorkspaceActivity), [`Webhooks.IterateWorkspaceActivity`](https://nextmail.sh/docs/go/reference/webhooks#iterateWorkspaceActivity), [`Webhooks.ListActivity`](https://nextmail.sh/docs/go/reference/webhooks#listActivity), [`Webhooks.ListAllActivity`](https://nextmail.sh/docs/go/reference/webhooks#listAllActivity), [`Webhooks.IterateActivity`](https://nextmail.sh/docs/go/reference/webhooks#iterateActivity); Java [`webhooks().listWorkspaceActivity`](https://nextmail.sh/docs/java/reference/webhooks#listWorkspaceActivity), [`webhooks().listAllWorkspaceActivity`](https://nextmail.sh/docs/java/reference/webhooks#listAllWorkspaceActivity), [`webhooks().iterateWorkspaceActivity`](https://nextmail.sh/docs/java/reference/webhooks#iterateWorkspaceActivity), [`webhooks().listActivity`](https://nextmail.sh/docs/java/reference/webhooks#listActivity), [`webhooks().listAllActivity`](https://nextmail.sh/docs/java/reference/webhooks#listAllActivity), [`webhooks().iterateActivity`](https://nextmail.sh/docs/java/reference/webhooks#iterateActivity); C# [`Webhooks.ListWorkspaceActivityAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listWorkspaceActivity), [`Webhooks.ListAllWorkspaceActivityAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listAllWorkspaceActivity), [`Webhooks.IterateWorkspaceActivityAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#iterateWorkspaceActivity), [`Webhooks.ListActivityAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listActivity), [`Webhooks.ListAllActivityAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listAllActivity), [`Webhooks.IterateActivityAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#iterateActivity).

### `getWebhook`

One webhook endpoint: where it posts, whether it is on and why not, which events it asked for, which addresses it hears about, and when it last delivered. The signing secret is never shown.

- Scopes: `webhooks:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The webhook endpoint, by its id (whe_…). listWebhooks names every one.

Also available in: API [`GET /webhooks`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks), [`GET /webhooks/{id}`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-id); TypeScript [`nextmail.webhooks.list()`](https://nextmail.sh/docs/sdk/reference/webhooks#list), [`nextmail.webhooks.listAll()`](https://nextmail.sh/docs/sdk/reference/webhooks#listAll), [`nextmail.webhooks.iterate()`](https://nextmail.sh/docs/sdk/reference/webhooks#iterate), [`nextmail.webhooks.get()`](https://nextmail.sh/docs/sdk/reference/webhooks#get); Python [`webhooks.list()`](https://nextmail.sh/docs/python/reference/webhooks#list), [`webhooks.list_all()`](https://nextmail.sh/docs/python/reference/webhooks#listAll), [`webhooks.iterate()`](https://nextmail.sh/docs/python/reference/webhooks#iterate), [`webhooks.get()`](https://nextmail.sh/docs/python/reference/webhooks#get); Ruby [`webhooks.list`](https://nextmail.sh/docs/ruby/reference/webhooks#list), [`webhooks.list_all`](https://nextmail.sh/docs/ruby/reference/webhooks#listAll), [`webhooks.iterate`](https://nextmail.sh/docs/ruby/reference/webhooks#iterate), [`webhooks.get`](https://nextmail.sh/docs/ruby/reference/webhooks#get); PHP [`webhooks->list`](https://nextmail.sh/docs/php/reference/webhooks#list), [`webhooks->listAll`](https://nextmail.sh/docs/php/reference/webhooks#listAll), [`webhooks->iterate`](https://nextmail.sh/docs/php/reference/webhooks#iterate), [`webhooks->get`](https://nextmail.sh/docs/php/reference/webhooks#get); Go [`Webhooks.List`](https://nextmail.sh/docs/go/reference/webhooks#list), [`Webhooks.ListAll`](https://nextmail.sh/docs/go/reference/webhooks#listAll), [`Webhooks.Iterate`](https://nextmail.sh/docs/go/reference/webhooks#iterate), [`Webhooks.Get`](https://nextmail.sh/docs/go/reference/webhooks#get); Java [`webhooks().list`](https://nextmail.sh/docs/java/reference/webhooks#list), [`webhooks().listAll`](https://nextmail.sh/docs/java/reference/webhooks#listAll), [`webhooks().iterate`](https://nextmail.sh/docs/java/reference/webhooks#iterate), [`webhooks().get`](https://nextmail.sh/docs/java/reference/webhooks#get); C# [`Webhooks.ListAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#list), [`Webhooks.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#listAll), [`Webhooks.IterateAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#iterate), [`Webhooks.GetAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#get).

### `createWebhook`

Add a webhook endpoint: an https URL that Nextmail posts signed events to. Name the events it wants, from listWebhookEvents; with none it gets every email event except email.replied. Allowlists narrow it to some addresses or domains. The answer holds the signing secret, shown this once.

- Scopes: `webhooks:write`.
- The app's assistant always asks first.
- Asks for a verification code, the same as [`POST /webhooks`](https://nextmail.sh/docs/api/reference/webhooks#post-webhooks).
- Toolkit: `workspace`.

**Inputs**

- `url` (`string`, required, 1 to 2048 characters)
- `eventTypes` (`string[]`, up to 51 items, one of `"email.received"`, `"email.replied"`, `"email.sent"`, `"email.failed"`, `"email.cancelled"`, `"email.scheduled"`, `"email.queued"`, `"email.delivered"`, `"email.delivery_delayed"`, `"email.bounced"`, `"email.complained"`, `"email.suppressed"`, `"email.opened"`, `"email.clicked"`, `"email.downloaded"`, `"domain.verified"`, `"domain.sending_changed"`, `"domain.deleted"`, `"suppression.added"`, `"suppression.removed"`, `"file.uploaded"`, `"file.deleted"`, `"form.submitted"`, `"form.confirmed"`, `"automation.entered"`, `"automation.exited"`, `"automation.paused"`, `"automation.resumed"`, `"automation.webhook"`, `"contact.created"`, `"contact.updated"`, `"contact.deleted"`, `"contact.unsubscribed"`, `"contact.resubscribed"`, `"sending.paused"`, `"sending.resumed"`, `"connector.connected"`, `"connector.disconnected"`, `"connector.needs_attention"`, `"task.run.completed"`, `"task.run.failed"`, `"task.run.cancelled"`, `"approval.requested"`, `"booking.created"`, `"booking.confirmed"`, `"booking.rescheduled"`, `"booking.cancelled"`, `"broadcast.sending"`, `"broadcast.sent"`, `"broadcast.failed"`, `"broadcast.cancelled"`)
- `description` (`string`, up to 200 characters)
- `addressAllowlist` (`string[]`, up to 50 items): Only events about these addresses. What you pass replaces the list.
- `domainAllowlist` (`string[]`, up to 25 items): Only events about addresses on these domains. What you pass replaces the list.

Also available in: API [`POST /webhooks`](https://nextmail.sh/docs/api/reference/webhooks#post-webhooks); TypeScript [`nextmail.webhooks.create()`](https://nextmail.sh/docs/sdk/reference/webhooks#create); Python [`webhooks.create()`](https://nextmail.sh/docs/python/reference/webhooks#create); Ruby [`webhooks.create`](https://nextmail.sh/docs/ruby/reference/webhooks#create); PHP [`webhooks->create`](https://nextmail.sh/docs/php/reference/webhooks#create); Go [`Webhooks.Create`](https://nextmail.sh/docs/go/reference/webhooks#create); Java [`webhooks().create`](https://nextmail.sh/docs/java/reference/webhooks#create); C# [`Webhooks.CreateAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#create).

### `updateWebhook`

Change a webhook endpoint: its URL, the events it wants, its description, its allowlists, or switch it on or off with enabled. Switching on clears an automatic disable. Lists you pass replace what it had.

- Scopes: `webhooks:write`.
- The app's assistant always asks first.
- Asks for a verification code, the same as [`PATCH /webhooks/{id}`](https://nextmail.sh/docs/api/reference/webhooks#patch-webhooks-id).
- Toolkit: `workspace`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The webhook endpoint, by its id (whe_…). listWebhooks names every one.
- `url` (`string`, 1 to 2048 characters)
- `eventTypes` (`string[]`, up to 51 items, one of `"email.received"`, `"email.replied"`, `"email.sent"`, `"email.failed"`, `"email.cancelled"`, `"email.scheduled"`, `"email.queued"`, `"email.delivered"`, `"email.delivery_delayed"`, `"email.bounced"`, `"email.complained"`, `"email.suppressed"`, `"email.opened"`, `"email.clicked"`, `"email.downloaded"`, `"domain.verified"`, `"domain.sending_changed"`, `"domain.deleted"`, `"suppression.added"`, `"suppression.removed"`, `"file.uploaded"`, `"file.deleted"`, `"form.submitted"`, `"form.confirmed"`, `"automation.entered"`, `"automation.exited"`, `"automation.paused"`, `"automation.resumed"`, `"automation.webhook"`, `"contact.created"`, `"contact.updated"`, `"contact.deleted"`, `"contact.unsubscribed"`, `"contact.resubscribed"`, `"sending.paused"`, `"sending.resumed"`, `"connector.connected"`, `"connector.disconnected"`, `"connector.needs_attention"`, `"task.run.completed"`, `"task.run.failed"`, `"task.run.cancelled"`, `"approval.requested"`, `"booking.created"`, `"booking.confirmed"`, `"booking.rescheduled"`, `"booking.cancelled"`, `"broadcast.sending"`, `"broadcast.sent"`, `"broadcast.failed"`, `"broadcast.cancelled"`)
- `description` (`string`, nullable, up to 200 characters)
- `enabled` (`boolean`)
- `addressAllowlist` (`string[]`, up to 50 items): Only events about these addresses. What you pass replaces the list.
- `domainAllowlist` (`string[]`, up to 25 items): Only events about addresses on these domains. What you pass replaces the list.

Also available in: API [`PATCH /webhooks/{id}`](https://nextmail.sh/docs/api/reference/webhooks#patch-webhooks-id); TypeScript [`nextmail.webhooks.update()`](https://nextmail.sh/docs/sdk/reference/webhooks#update); Python [`webhooks.update()`](https://nextmail.sh/docs/python/reference/webhooks#update); Ruby [`webhooks.update`](https://nextmail.sh/docs/ruby/reference/webhooks#update); PHP [`webhooks->update`](https://nextmail.sh/docs/php/reference/webhooks#update); Go [`Webhooks.Update`](https://nextmail.sh/docs/go/reference/webhooks#update); Java [`webhooks().update`](https://nextmail.sh/docs/java/reference/webhooks#update); C# [`Webhooks.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#update).

### `deleteWebhook`

Remove a webhook endpoint. Nothing is posted to it from then on, and its delivery log and history stay readable. updateWebhook with enabled false is the reversible way to stop one.

- Scopes: `webhooks:write`.
- The app's assistant always asks first.
- Toolkit: `workspace`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The webhook endpoint, by its id (whe_…). listWebhooks names every one.

Also available in: API [`DELETE /webhooks/{id}`](https://nextmail.sh/docs/api/reference/webhooks#delete-webhooks-id); TypeScript [`nextmail.webhooks.delete()`](https://nextmail.sh/docs/sdk/reference/webhooks#delete); Python [`webhooks.delete()`](https://nextmail.sh/docs/python/reference/webhooks#delete); Ruby [`webhooks.delete`](https://nextmail.sh/docs/ruby/reference/webhooks#delete); PHP [`webhooks->delete`](https://nextmail.sh/docs/php/reference/webhooks#delete); Go [`Webhooks.Delete`](https://nextmail.sh/docs/go/reference/webhooks#delete); Java [`webhooks().delete`](https://nextmail.sh/docs/java/reference/webhooks#delete); C# [`Webhooks.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#delete).

### `rotateWebhookSecret`

Give a webhook endpoint a new signing secret. For 24 hours every delivery is signed with the old secret as well, so the receiver keeps verifying while it is given the new one. The new secret is shown once, in the answer to this call.

- Scopes: `webhooks:write`.
- MCP only, not in the app's assistant.
- Toolkit: `workspace`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The webhook endpoint, by its id (whe_…). listWebhooks names every one.

Also available in: API [`POST /webhooks/{id}/rotate-secret`](https://nextmail.sh/docs/api/reference/webhooks#post-webhooks-id-rotate-secret); TypeScript [`nextmail.webhooks.rotateSecret()`](https://nextmail.sh/docs/sdk/reference/webhooks#rotateSecret); Python [`webhooks.rotate_secret()`](https://nextmail.sh/docs/python/reference/webhooks#rotateSecret); Ruby [`webhooks.rotate_secret`](https://nextmail.sh/docs/ruby/reference/webhooks#rotateSecret); PHP [`webhooks->rotateSecret`](https://nextmail.sh/docs/php/reference/webhooks#rotateSecret); Go [`Webhooks.RotateSecret`](https://nextmail.sh/docs/go/reference/webhooks#rotateSecret); Java [`webhooks().rotateSecret`](https://nextmail.sh/docs/java/reference/webhooks#rotateSecret); C# [`Webhooks.RotateSecretAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#rotateSecret).

### `testWebhook`

Post one signed test event to a webhook endpoint now and report what it answered. It reaches the real receiver, and it is recorded in the activity of the endpoint.

- Scopes: `webhooks:write`.
- The app's assistant always asks first.
- Toolkit: `workspace`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The webhook endpoint, by its id (whe_…). listWebhooks names every one.

Also available in: API [`POST /webhooks/{id}/test`](https://nextmail.sh/docs/api/reference/webhooks#post-webhooks-id-test); TypeScript [`nextmail.webhooks.test()`](https://nextmail.sh/docs/sdk/reference/webhooks#test); Python [`webhooks.test()`](https://nextmail.sh/docs/python/reference/webhooks#test); Ruby [`webhooks.test`](https://nextmail.sh/docs/ruby/reference/webhooks#test); PHP [`webhooks->test`](https://nextmail.sh/docs/php/reference/webhooks#test); Go [`Webhooks.Test`](https://nextmail.sh/docs/go/reference/webhooks#test); Java [`webhooks().test`](https://nextmail.sh/docs/java/reference/webhooks#test); C# [`Webhooks.TestAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#test).

### `getWebhookStats`

How the webhook deliveries went inside a window: attempts, delivered and failed, the median time a receiver took, a count per bucket of grain, the events sent most and the response codes. Every endpoint, or the ones endpointIds names. The window is the last 30 days unless since or until say otherwise.

- Scopes: `webhooks:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `endpointIds` (`string[]`, up to 50 items)
- `since` (`string`): An ISO 8601 instant, such as 2026-09-01T00:00:00Z.
- `until` (`string`): An ISO 8601 instant, such as 2026-09-01T00:00:00Z.
- `grain` (`string`, one of `"minute"`, `"hour"`, `"day"`)
- `offsetMinutes` (`integer`, at least -840, at most 840)

Also available in: API [`GET /webhooks/stats`](https://nextmail.sh/docs/api/reference/webhooks#get-webhooks-stats); TypeScript [`nextmail.webhooks.stats()`](https://nextmail.sh/docs/sdk/reference/webhooks#stats); Python [`webhooks.stats()`](https://nextmail.sh/docs/python/reference/webhooks#stats); Ruby [`webhooks.stats`](https://nextmail.sh/docs/ruby/reference/webhooks#stats); PHP [`webhooks->stats`](https://nextmail.sh/docs/php/reference/webhooks#stats); Go [`Webhooks.Stats`](https://nextmail.sh/docs/go/reference/webhooks#stats); Java [`webhooks().stats`](https://nextmail.sh/docs/java/reference/webhooks#stats); C# [`Webhooks.StatsAsync`](https://nextmail.sh/docs/csharp/reference/webhooks#stats).

### `getApiKeyStats`

What the API keys of this workspace did inside a window, as the Analytics tab of the API keys page shows it: the mail they sent and what became of it, the calls refused for a bad secret, the requests made and how many failed, the routes called most and the status codes returned. Every key, or the ones keyIds names. The window is the last 30 days unless since or until say otherwise. Only the owner of the workspace can read it.

- Scopes: `api-keys:read`, `emails:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `keyIds` (`string[]`, up to 50 items)
- `since` (`string`): An ISO 8601 instant, such as 2026-09-01T00:00:00Z.
- `until` (`string`): An ISO 8601 instant, such as 2026-09-01T00:00:00Z.
- `grain` (`string`, one of `"minute"`, `"hour"`, `"day"`)
- `offsetMinutes` (`integer`, at least -840, at most 840)

Also available in: API [`GET /keys/stats`](https://nextmail.sh/docs/api/reference/api-keys#get-keys-stats); TypeScript [`nextmail.keys.stats()`](https://nextmail.sh/docs/sdk/reference/keys#stats); Python [`keys.stats()`](https://nextmail.sh/docs/python/reference/keys#stats); Ruby [`keys.stats`](https://nextmail.sh/docs/ruby/reference/keys#stats); PHP [`keys->stats`](https://nextmail.sh/docs/php/reference/keys#stats); Go [`Keys.Stats`](https://nextmail.sh/docs/go/reference/keys#stats); Java [`keys().stats`](https://nextmail.sh/docs/java/reference/keys#stats); C# [`Keys.StatsAsync`](https://nextmail.sh/docs/csharp/reference/keys#stats).