Keys and webhooks

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.