@productcraft/mail 0.2.4 → 1.0.0

package/api.md

@@ -0,0 +1,3716 @@
+# @productcraft/mail API reference
+
+<!-- Generated by scripts/gen-sdk.mjs from Specs/mail.json. Do not edit. -->
+<!-- snippet-preamble: import { Mail } from "@productcraft/mail"; const mail = new Mail(); -->
+
+Every method of `Mail`, grouped by resource. Types are under the `Mail` namespace (`import type { Mail } from "@productcraft/mail"`). Every method takes per-request options last (`{ idempotencyKey, timeout, maxRetries, headers, signal, workspaceId }`).
+
+## brand
+
+### `mail.brand.reset(options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/brand` → `void`
+
+Remove all brand customizations and revert to platform defaults.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.brand.reset();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-brand)
+
+### `mail.brand.retrieve(options?)`
+
+`GET /v1/workspaces/{workspace_id}/brand` → `Mail.Brand`
+
+Get the resolved brand tokens for the workspace. Always returns a complete object, with platform defaults filling in any unset fields.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const brand = await mail.brand.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-brand)
+
+### `mail.brand.update(params?, options?)`
+
+`PUT /v1/workspaces/{workspace_id}/brand` → `Mail.Brand`
+
+Replace the workspace brand. Any field omitted from the body is reset to the platform default for that field. To partially-update, send back what GET returned with the desired diff applied.
+
+- Params: `Mail.BrandUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure on the brand payload. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const brand = await mail.brand.update({ background_color: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#put-v1-workspaces-workspace-id-brand)
+
+## broadcasts
+
+### `mail.broadcasts.audience(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/broadcasts/audience` → `Mail.BroadcastAudience`
+
+Count a broadcast audience.
+
+How many contacts a broadcast to this segment and/or topic would reach if it were sent now: members of the segment, subscribed to the topic, minus anyone unsubscribed or on the suppression list.
+
+- Params: `Mail.BroadcastAudienceParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `AUDIENCE_REQUIRED`, `SEGMENT_NOT_FOUND`, `TOPIC_NOT_FOUND` | Neither given (`AUDIENCE_REQUIRED`), or one does not exist in this workspace (`SEGMENT_NOT_FOUND` / `TOPIC_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcastAudience = await mail.broadcasts.audience();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-broadcasts-audience)
+
+### `mail.broadcasts.cancel(broadcastId, options?)`
+
+`POST /v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/cancel` → `Mail.Broadcast`
+
+Cancel a scheduled or sending broadcast.
+
+Recipients not sent yet are marked `canceled`; messages already handed off are not recalled.
+
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `BROADCAST_NOT_FOUND` | No such broadcast (`BROADCAST_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `BROADCAST_NOT_CANCELABLE`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Draft, sent or already canceled (`BROADCAST_NOT_CANCELABLE`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcast = await mail.broadcasts.cancel("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-broadcasts-broadcast-id-cancel)
+
+### `mail.broadcasts.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/broadcasts` → `Mail.Broadcast`
+
+Create a broadcast (draft).
+
+Content is a saved template (`template_name`) or inline Handlebars (`html`, `subject`, optional `text`). The audience is a segment, a topic, or both. Nothing is sent until `POST .../send`.
+
+- Params: `Mail.BroadcastCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `SEGMENT_NOT_FOUND`, `TOPIC_NOT_FOUND`, `BROADCAST_CONTENT_CONFLICT` | `segment_id` or `topic_id` does not name one of this workspace's (`SEGMENT_NOT_FOUND` / `TOPIC_NOT_FOUND`), or both `template_name` and `html` were given (`BROADCAST_CONTENT_CONFLICT`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcast = await mail.broadcasts.create({ name: "October product update" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-broadcasts)
+
+### `mail.broadcasts.delete(broadcastId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}` → `void`
+
+Delete a broadcast.
+
+Drafts, sent and canceled broadcasts, with their recipient list. The messages themselves stay in the message log.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `BROADCAST_NOT_FOUND` | No such broadcast (`BROADCAST_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `BROADCAST_NOT_DELETABLE` | Scheduled or sending: cancel it first (`BROADCAST_NOT_DELETABLE`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.broadcasts.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-broadcasts-broadcast-id)
+
+### `mail.broadcasts.duplicate(broadcastId, options?)`
+
+`POST /v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/duplicate` → `Mail.Broadcast`
+
+Duplicate a broadcast.
+
+A new draft with the same content and audience.
+
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `BROADCAST_NOT_FOUND` | No such broadcast (`BROADCAST_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcast = await mail.broadcasts.duplicate("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-broadcasts-broadcast-id-duplicate)
+
+### `mail.broadcasts.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/broadcasts` → `PagePromise<Mail.Broadcast>`
+
+List broadcasts, newest first.
+
+- Params: `Mail.BroadcastListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const broadcast of mail.broadcasts.list()) {
+  console.log(broadcast);
+}
+const page = await mail.broadcasts.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-broadcasts)
+
+### `mail.broadcasts.retrieve(broadcastId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}` → `Mail.Broadcast`
+
+Get a broadcast.
+
+Includes `counts` once sending has started: recipients, sent, delivered, bounced, complained, opened, clicked, unsubscribed.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `BROADCAST_NOT_FOUND` | No such broadcast (`BROADCAST_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcast = await mail.broadcasts.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-broadcasts-broadcast-id)
+
+### `mail.broadcasts.send(broadcastId, params?, options?)`
+
+`POST /v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/send` → `Mail.Broadcast`
+
+Send or schedule a broadcast.
+
+Now, or at `scheduled_at`. When sending starts the audience is frozen (segment ∩ topic subscribers − unsubscribed − suppression list) and the messages go out at the broadcast rate (default 120 per minute; separate from the transactional limit), on the marketing stream, each with a one-click unsubscribe link and `List-Unsubscribe` headers. The send survives restarts: it continues from the recipients not yet sent.
+
+- Params: `Mail.BroadcastSendParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `BROADCAST_NOT_FOUND` | No such broadcast (`BROADCAST_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `BROADCAST_NOT_DRAFT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Not a draft (`BROADCAST_NOT_DRAFT`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `UNSUBSCRIBE_LINK_REQUIRED`, `BROADCAST_NOT_READY`, `BROADCAST_AUDIENCE_EMPTY`, `INVALID_FROM_ADDRESS`, `from_domain_not_verified` | Not ready: `UNSUBSCRIBE_LINK_REQUIRED` (the body does not contain `{{{unsubscribe_url}}}`) or `BROADCAST_NOT_READY` (`details.problems`: no audience, no content, no subject, missing template, no From); `BROADCAST_AUDIENCE_EMPTY` (nobody to send to); `INVALID_FROM_ADDRESS`; or `from_domain_not_verified` (`details: { fqdn, reason }`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcast = await mail.broadcasts.send("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { scheduled_at: "2026-11-02T09:00:00Z" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-broadcasts-broadcast-id-send)
+
+### `mail.broadcasts.update(broadcastId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}` → `Mail.Broadcast`
+
+Update a draft broadcast.
+
+Only drafts can change; null clears an optional field.
+
+- Params: `Mail.BroadcastUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `BROADCAST_NOT_FOUND` | No such broadcast (`BROADCAST_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `BROADCAST_NOT_DRAFT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Not a draft any more (`BROADCAST_NOT_DRAFT`, `details.status`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `SEGMENT_NOT_FOUND`, `TOPIC_NOT_FOUND`, `BROADCAST_CONTENT_CONFLICT` | `segment_id` or `topic_id` does not name one of this workspace's (`SEGMENT_NOT_FOUND` / `TOPIC_NOT_FOUND`), or both `template_name` and `html` were given (`BROADCAST_CONTENT_CONFLICT`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcast = await mail.broadcasts.update("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { from: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-broadcasts-broadcast-id)
+
+## broadcasts.clickedLinks
+
+### `mail.broadcasts.clickedLinks.list(broadcastId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/clicked-links` → `Mail.ClickedLinks`
+
+Links clicked in a broadcast.
+
+Most clicked first. Empty until click tracking is enabled.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `BROADCAST_NOT_FOUND` | No such broadcast (`BROADCAST_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const clickedLinks = await mail.broadcasts.clickedLinks.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-broadcasts-broadcast-id-clicked-links)
+
+## broadcasts.recipients
+
+### `mail.broadcasts.recipients.list(broadcastId, params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/recipients` → `PagePromise<Mail.BroadcastRecipient>`
+
+List a broadcast's recipients.
+
+In send order, with each message status.
+
+- Params: `Mail.BroadcastRecipientListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `BROADCAST_NOT_FOUND` | No such broadcast (`BROADCAST_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const recipient of mail.broadcasts.recipients.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b")) {
+  console.log(recipient);
+}
+const page = await mail.broadcasts.recipients.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-broadcasts-broadcast-id-recipients)
+
+## broadcasts.settings
+
+### `mail.broadcasts.settings.retrieve(options?)`
+
+`GET /v1/workspaces/{workspace_id}/broadcast-settings` → `Mail.BroadcastSettings`
+
+Get the broadcast settings.
+
+The messages-per-minute pace broadcasts go out at.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcastSettings = await mail.broadcasts.settings.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-broadcast-settings)
+
+### `mail.broadcasts.settings.update(params, options?)`
+
+`PUT /v1/workspaces/{workspace_id}/broadcast-settings` → `Mail.BroadcastSettings`
+
+Update the broadcast settings.
+
+Set the workspace campaign pace (1 to 300 messages per minute; null for the default, 120). It never affects transactional sends, which have their own limit.
+
+- Params: `Mail.BroadcastSettingsUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const broadcastSettings = await mail.broadcasts.settings.update({ rate_per_minute: 1 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#put-v1-workspaces-workspace-id-broadcast-settings)
+
+## contacts
+
+### `mail.contacts.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/contacts` → `Mail.Contact`
+
+Create a contact.
+
+Emits `contact.created`. Without `consent`, the contact receives only topics it is explicitly opted in to.
+
+- Params: `Mail.ContactCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `TOPIC_NOT_FOUND` | A `topics[].id` is not a topic of this workspace (`TOPIC_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `CONTACT_EXISTS`, `CONTACT_LIMIT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | A contact with this email exists (`CONTACT_EXISTS`), the workspace has 100,000 contacts (`CONTACT_LIMIT`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `UNKNOWN_CONTACT_PROPERTY`, `INVALID_CONTACT_PROPERTY_VALUE` | A `properties` key is not a defined property (`UNKNOWN_CONTACT_PROPERTY`) or its value has the wrong type (`INVALID_CONTACT_PROPERTY_VALUE`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contact = await mail.contacts.create({ email: "ada@example.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-contacts)
+
+### `mail.contacts.delete(contact, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/contacts/{contact}` → `void`
+
+Delete a contact.
+
+Removes the contact, its properties and its topic choices. Emits `contact.deleted`. To stop mailing someone, unsubscribe them instead: a deleted contact that later receives a topic send is refused (`no_consent`), but its opt-out is forgotten.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_NOT_FOUND` | No such contact (`CONTACT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.contacts.delete("ada@example.com");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-contacts-contact)
+
+### `mail.contacts.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/contacts` → `PagePromise<Mail.Contact>`
+
+List contacts, newest first.
+
+- Params: `Mail.ContactListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const contact of mail.contacts.list()) {
+  console.log(contact);
+}
+const page = await mail.contacts.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-contacts)
+
+### `mail.contacts.retrieve(contact, options?)`
+
+`GET /v1/workspaces/{workspace_id}/contacts/{contact}` → `Mail.Contact`
+
+Get a contact by id or email.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_NOT_FOUND` | No such contact (`CONTACT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contact = await mail.contacts.retrieve("ada@example.com");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-contacts-contact)
+
+### `mail.contacts.update(contact, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/contacts/{contact}` → `Mail.Contact`
+
+Update a contact.
+
+The email cannot change (delete and re-create). Emits `contact.updated` when something changed.
+
+- Params: `Mail.ContactUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_NOT_FOUND` | No such contact (`CONTACT_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `UNKNOWN_CONTACT_PROPERTY`, `INVALID_CONTACT_PROPERTY_VALUE` | `UNKNOWN_CONTACT_PROPERTY` or `INVALID_CONTACT_PROPERTY_VALUE`. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contact = await mail.contacts.update("ada@example.com", { consent: { consented_at: "2026-10-24T09:00:00Z", source: "signup-form-2026" } });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-contacts-contact)
+
+## contacts.imports
+
+### `mail.contacts.imports.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/contacts/imports` → `Mail.ContactImport`
+
+Import contacts from a CSV file.
+
+Queues the file and returns the import (`status: queued`); poll `GET .../contacts/imports/{id}` for progress. At most 10 MB and 100,000 rows, two imports running per workspace. Rows that assert consent (`consent` true or a `consented_at` date) are recorded with it and opted in to `topic_ids`; every other row starts without consent. An import emits no per-contact webhook events.
+
+- Params: `Mail.ContactImportCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `TOPIC_NOT_FOUND` | A `topic_ids` entry is not a topic of this workspace (`TOPIC_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IMPORT_IN_PROGRESS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Two imports are already running (`IMPORT_IN_PROGRESS`), or `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different body or route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 413 | `APIError` | `PAYLOAD_TOO_LARGE`, `IMPORT_TOO_LARGE` | The CSV is larger than 10 MB (`IMPORT_TOO_LARGE`). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_CSV` | Empty file, or no header line with an `email` column (`INVALID_CSV`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contactImport = await mail.contacts.imports.create({
+  csv: "email,first_name,consent,consented_at\nada@example.com,Ada,true,2026-10-01T09:00:00Z\n",
+  on_conflict: "upsert",
+});
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-contacts-imports)
+
+### `mail.contacts.imports.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/contacts/imports` → `PagePromise<Mail.ContactImport>`
+
+List contact imports, newest first.
+
+- Params: `Mail.ContactImportListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const importItem of mail.contacts.imports.list()) {
+  console.log(importItem);
+}
+const page = await mail.contacts.imports.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-contacts-imports)
+
+### `mail.contacts.imports.retrieve(importId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/contacts/imports/{import_id}` → `Mail.ContactImport`
+
+Get a contact import and its progress.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `IMPORT_NOT_FOUND` | No such import in this workspace (`IMPORT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contactImport = await mail.contacts.imports.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-contacts-imports-import-id)
+
+## contacts.properties
+
+### `mail.contacts.properties.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/contact-properties` → `Mail.ContactProperty`
+
+Define a contact property.
+
+At most 50 per workspace.
+
+- Params: `Mail.ContactPropertyCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `CONTACT_PROPERTY_EXISTS`, `CONTACT_PROPERTY_LIMIT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | The key exists (`CONTACT_PROPERTY_EXISTS`), the workspace has 50 properties (`CONTACT_PROPERTY_LIMIT`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `RESERVED_PROPERTY_KEY`, `INVALID_CONTACT_PROPERTY_VALUE` | The key is a contact field (`RESERVED_PROPERTY_KEY`) or the fallback does not match the type (`INVALID_CONTACT_PROPERTY_VALUE`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contactProperty = await mail.contacts.properties.create({ key: "company", type: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-contact-properties)
+
+### `mail.contacts.properties.delete(propertyId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/contact-properties/{property_id}` → `void`
+
+Delete a contact property.
+
+Values already stored on contacts stay, but are no longer validated; define the key again to use it.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_PROPERTY_NOT_FOUND` | No such property (`CONTACT_PROPERTY_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.contacts.properties.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-contact-properties-property-id)
+
+### `mail.contacts.properties.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/contact-properties` → `PagePromise<Mail.ContactProperty>`
+
+List contact properties, newest first.
+
+- Params: `Mail.ContactPropertyListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const property of mail.contacts.properties.list()) {
+  console.log(property);
+}
+const page = await mail.contacts.properties.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-contact-properties)
+
+### `mail.contacts.properties.retrieve(propertyId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/contact-properties/{property_id}` → `Mail.ContactProperty`
+
+Get a contact property.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_PROPERTY_NOT_FOUND` | No such property (`CONTACT_PROPERTY_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contactProperty = await mail.contacts.properties.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-contact-properties-property-id)
+
+### `mail.contacts.properties.update(propertyId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/contact-properties/{property_id}` → `Mail.ContactProperty`
+
+Change a contact property's fallback value.
+
+The key and type are fixed once created.
+
+- Params: `Mail.ContactPropertyUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_PROPERTY_NOT_FOUND` | No such property (`CONTACT_PROPERTY_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_CONTACT_PROPERTY_VALUE` | The fallback does not match the type (`INVALID_CONTACT_PROPERTY_VALUE`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contactProperty = await mail.contacts.properties.update("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { fallback_value: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-contact-properties-property-id)
+
+## contacts.segments
+
+### `mail.contacts.segments.add(contact, segmentId, options?)`
+
+`POST /v1/workspaces/{workspace_id}/contacts/{contact}/segments/{segment_id}` → `Mail.SegmentMembership`
+
+Add a contact to a static segment.
+
+Adds the contact. Adding a contact that is already a member changes nothing and answers the same way, with `added_at` from the first time.
+
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_NOT_FOUND`, `SEGMENT_NOT_FOUND` | No such contact (`CONTACT_NOT_FOUND`) or segment (`SEGMENT_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `SEGMENT_RULE_BASED` | The segment is rule-based: its members follow the rule (`SEGMENT_RULE_BASED`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const segmentMembership = await mail.contacts.segments.add("ada@example.com", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-contacts-contact-segments-segment-id)
+
+### `mail.contacts.segments.delete(contact, segmentId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/contacts/{contact}/segments/{segment_id}` → `void`
+
+Remove a contact from a static segment.
+
+204 whether or not it was a member.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_NOT_FOUND`, `SEGMENT_NOT_FOUND` | No such contact (`CONTACT_NOT_FOUND`) or segment (`SEGMENT_NOT_FOUND`). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `SEGMENT_RULE_BASED` | The segment is rule-based (`SEGMENT_RULE_BASED`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.contacts.segments.delete("ada@example.com", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-contacts-contact-segments-segment-id)
+
+### `mail.contacts.segments.list(contact, options?)`
+
+`GET /v1/workspaces/{workspace_id}/contacts/{contact}/segments` → `Mail.ContactSegments`
+
+List a contact's segments.
+
+Static segments it was added to and rule segments it matches now.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_NOT_FOUND` | No such contact (`CONTACT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contactSegments = await mail.contacts.segments.list("ada@example.com");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-contacts-contact-segments)
+
+## contacts.topics
+
+### `mail.contacts.topics.list(contact, options?)`
+
+`GET /v1/workspaces/{workspace_id}/contacts/{contact}/topics` → `Mail.ContactTopics`
+
+List a contact's topic subscriptions.
+
+Every topic of the workspace, with the contact's own choice and whether a topic send would reach it now (and why).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_NOT_FOUND` | No such contact (`CONTACT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contactTopics = await mail.contacts.topics.list("ada@example.com");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-contacts-contact-topics)
+
+### `mail.contacts.topics.update(contact, params, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/contacts/{contact}/topics` → `Mail.ContactTopics`
+
+Opt a contact in to or out of topics.
+
+Records the contact's choice per topic (an explicit `opt_in` is consent for that topic). A global unsubscribe still wins: clear it with `PATCH .../contacts/{contact}` `unsubscribed: false`. Emits `contact.updated`.
+
+- Params: `Mail.ContactTopicUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `CONTACT_NOT_FOUND`, `TOPIC_NOT_FOUND` | No such contact (`CONTACT_NOT_FOUND`) or topic (`TOPIC_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const contactTopics = await mail.contacts.topics.update("ada@example.com", { topics: [{ id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b", subscription: "opt_in" }] });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-contacts-contact-topics)
+
+## deliverability
+
+### `mail.deliverability.retrieve(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/deliverability` → `Mail.Deliverability`
+
+Deliverability verdict for the workspace over a lookback window. `unconfirmed` means mail was handed off and nothing came back either way — it is not a synonym for healthy.
+
+- Params: `Mail.DeliverabilityRetrieveParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | window_days out of range. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Not authenticated. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Missing mail.message.read, or the mail service is not enabled. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const deliverability = await mail.deliverability.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-deliverability)
+
+## domains
+
+### `mail.domains.create(params?, options?)`
+
+`POST /v1/workspaces/{workspace_id}/domains` → `Mail.Domain`
+
+Register a domain for a workspace.
+
+Accepts Resend's create-domain body as well as ours: `name` for `fqdn`, `capabilities` for `intent`, `custom_return_path` for the MAIL FROM label, and `region`, `tls`, `open_tracking`, `click_tracking`, `tracking_subdomain`. Defaults to sending only (`intent: send`), as Resend does. Options we do not offer yet are refused with 422 rather than ignored.
+
+- Params: `Mail.DomainCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `INVALID_CAPABILITIES`, `MAIL_FROM_NOT_SENDING` | Validation failure on the request body: no `fqdn`/`name`, `fqdn` and `name` disagree, `intent` and `capabilities` disagree or enable nothing (`INVALID_CAPABILITIES`), or `custom_return_path` on a receive-only domain (`MAIL_FROM_NOT_SENDING`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `MAIL_FROM_HOST_IN_USE`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Domain already registered (globally unique); `MAIL_FROM_HOST_IN_USE`: the `custom_return_path` host already has records that are not ours (listed in `details.found`); or `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different body or route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `REGION_NOT_AVAILABLE`, `TLS_ENFORCED_NOT_AVAILABLE`, `TRACKING_NOT_AVAILABLE` | `REGION_NOT_AVAILABLE`: `region` is not the region this deployment sends from (`details.available`); `TLS_ENFORCED_NOT_AVAILABLE`: `tls: enforced`; `TRACKING_NOT_AVAILABLE`: open/click tracking or a tracking subdomain. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const domain = await mail.domains.create({ capabilities: { receiving: "enabled", sending: "enabled" } });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-domains)
+
+### `mail.domains.delete(domainId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/domains/{domain_id}` → `void`
+
+Delete a domain (must have no active mailboxes left).
+
+Permanently deletes the domain, its DNS record set and its Amazon SES sending identity. Mailboxes you already deleted on it are erased with it, together with the mail they still held and its stored files; this cannot be undone. Refused with 409 `DOMAIN_HAS_MAILBOXES` while any mailbox on it is active.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `DOMAIN_HAS_MAILBOXES` | `DOMAIN_HAS_MAILBOXES`: the domain still has active mailboxes. `details.count` is how many; `details.mailboxes` lists them (`id`, `address`, first 100). Delete them, then try again. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+| 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `SES_IDENTITY_DELETE_FAILED` | `SES_IDENTITY_DELETE_FAILED`: the domain's Amazon SES identity could not be removed. Nothing was deleted; retry. |
+
+```ts
+await mail.domains.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-domains-domain-id)
+
+### `mail.domains.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/domains` → `PagePromise<Mail.Domain>`
+
+List domains registered to this workspace (newest first), cursor-paginated.
+
+- Params: `Mail.DomainListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid cursor, search term, or status filter. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const domain of mail.domains.list()) {
+  console.log(domain);
+}
+const page = await mail.domains.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-domains)
+
+### `mail.domains.lookup(params, options?)`
+
+`GET /v1/workspaces/{workspace_id}/domains/lookup` → `Mail.DomainLookup`
+
+Look up a domain before adding it: zone, DNS provider, Domain Connect support, a better subdomain, existing records.
+
+Creates nothing. Resolves only names at or under `fqdn` and its zone apex, plus the Domain Connect endpoints the zone advertises (fetched through the SSRF guard; cached per zone for an hour). Limited to 30 lookups per workspace per minute.
+
+- Params: `Mail.DomainLookupParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `fqdn` missing or not a domain name. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 30 lookups this minute (`RATE_LIMITED`). Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const domainLookup = await mail.domains.lookup({ fqdn: "acme.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-domains-lookup)
+
+### `mail.domains.retrieve(domainId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/domains/{domain_id}` → `Mail.DomainDetail`
+
+Get a single domain (with DNS instructions and its latest events).
+
+The domain with `verification_status`, `region`, the effective `dns_provider`, `recommended_pending`, its DNS instructions, and `events`: the latest 20 domain events, newest first.
+
+- Polling: `domains.poll(…)` waits for `status` ∈ `active`, `disabled`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `domain_id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const domainDetail = await mail.domains.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-domains-domain-id)
+
+### `mail.domains.testSend(domainId, params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/domains/{domain_id}/test-send` → `Mail.SendAccepted`
+
+Send a built-in test email from this domain, no template needed.
+
+Sends a fixed message (subject `[TEST] Sending from <domain> works`, a short body naming the domain and the From address) so a freshly verified domain can be tried before any template exists. The From address defaults to `test@<domain>` and must be at this exact domain. Like a template test send it skips the suppression list and the ordinary send limits, counts against the workspace test-send limit (30 per hour), and is recorded with `source: test_send`.
+
+- Params: `Mail.DomainTestSendParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `domain_id` is not a UUID, or the body is malformed (bad `to` or `from`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `DOMAIN_NOT_FOUND` | `DOMAIN_NOT_FOUND`: no such domain in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different body or route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `FROM_DOMAIN_MISMATCH`, `from_domain_not_verified`, `domain_not_verified_by_provider` | `FROM_DOMAIN_MISMATCH`: the From address is not at this domain; or `from_domain_not_verified` (body `code`, `details: { fqdn, reason }`): the domain is receive-only (`reason: not_registered`) or not verified yet (`reason: not_verified`); or `domain_not_verified_by_provider`: its DNS records have been broken for over 72 h (`health: failing`). Refused before anything is recorded or queued. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 30 test sends this hour in this workspace: `RATE_LIMITED` with `details: { window, limit, retry_after }`. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const sendAccepted = await mail.domains.testSend("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { to: "you@acme.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-domains-domain-id-test-send)
+
+### `mail.domains.update(domainId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/domains/{domain_id}` → `Mail.Domain`
+
+Update domain settings: capabilities, DNS provider hint, custom MAIL FROM subdomain, DMARC recommendation.
+
+`intent` (or Resend's `capabilities`) changes what the domain is used for. A pending domain just changes; a verified domain gaining sending or receiving has the new records checked live and is refused with 409 `CAPABILITY_NOT_VERIFIED` (the records to publish in `details.records`) until they pass. Turning receiving off is refused while active mailboxes exist (409 `DOMAIN_HAS_MAILBOXES`, the mailboxes in `details.mailboxes`; deleted mailboxes do not count); turning sending off also turns the custom MAIL FROM off. `tls`, `open_tracking`, `click_tracking` and `tracking_subdomain` are accepted for Resend compatibility; only the values in effect today pass (422 otherwise). `dns_provider` is the provider the setup wizard renders host names for. `mail_from_subdomain` sets the custom MAIL FROM label (`bounce` → `bounce.<fqdn>`; `null` turns it off): the domain's record set gains the MAIL FROM MX + SPF records, and once the domain is verified its MAIL FROM is pointed there (the default return address stays in use until the MX record is found, so mail never stops). Refused with 409 when that host already carries records that are not ours. `dmarc_managed: false` hides the `_dmarc` recommendation for domains whose DMARC is managed elsewhere (the policy is still detected and graded).
+
+- Params: `Mail.DomainUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `INVALID_CAPABILITIES`, `MAIL_FROM_NOT_SENDING` | Validation failure on the request body; `intent` and `capabilities` disagree or enable nothing (`INVALID_CAPABILITIES`); or `mail_from_subdomain` on a receive-only domain (`MAIL_FROM_NOT_SENDING`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `CAPABILITY_NOT_VERIFIED`, `DOMAIN_HAS_MAILBOXES`, `MAIL_FROM_HOST_IN_USE`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `CAPABILITY_NOT_VERIFIED`: a verified domain cannot gain sending or receiving until the new records verify (`details.failing`, `details.records`); `DOMAIN_HAS_MAILBOXES`: receiving cannot be turned off while active mailboxes exist (`details.count`, `details.mailboxes[].id\|address`); `MAIL_FROM_HOST_IN_USE`: the MAIL FROM host already has a CNAME, a foreign MX or a foreign SPF record (listed in `details.found`); or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `TLS_ENFORCED_NOT_AVAILABLE`, `TRACKING_NOT_AVAILABLE` | `TLS_ENFORCED_NOT_AVAILABLE`: `tls: enforced`; `TRACKING_NOT_AVAILABLE`: open/click tracking or a tracking subdomain. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | `mail_from_subdomain` or `intent` changed less than 10 seconds ago (`RATE_LIMITED`). Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const domain = await mail.domains.update("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { capabilities: { receiving: "enabled", sending: "enabled" } });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-domains-domain-id)
+
+### `mail.domains.verify(domainId, options?)`
+
+`POST /v1/workspaces/{workspace_id}/domains/{domain_id}/verify` → `Mail.Domain`
+
+Run a synchronous DNS check against this domain; flips status to active when the required record set passes.
+
+Legacy shape, kept as an alias of `POST .../dns-records/check`: returns the domain on success and a 400 with `dns_check_results` when a required record fails. New integrations should use `POST .../dns-records/check`, which returns per-record states.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Verification failed — one or more required records are still missing or wrong. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Verified less than 10 seconds ago (`RATE_LIMITED`). Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const domain = await mail.domains.verify("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-domains-domain-id-verify)
+
+## domains.dnsRecords
+
+### `mail.domains.dnsRecords.apply(domainId, params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/apply` → `Mail.DnsApplyResult`
+
+Set up the domain's DNS records in one step with a short-lived Cloudflare or DigitalOcean API token.
+
+Reads the zone through the provider's API and plans every record the domain needs: `create`, `update` (only ever an SPF merge into an existing SPF record, shown with `before`/`after`) or `skip` (already there). `dry_run: true` returns the plan and changes nothing; `dry_run: false` applies exactly that plan, runs a DNS check straight away and records `setup_method = provider_api`. Only names at or under the domain are written, nothing is ever deleted, and Cloudflare records are DNS-only (not proxied). The recommended DMARC record (`p=none`) is included when `include_dmarc` is true (the default) and no DMARC policy applies to the domain yet; an existing policy is never touched. Any blocking conflict refuses the whole apply with 409. The token is used for this request only: it is never stored, logged, queued or returned; revoke it afterwards (`warnings` says so when it could see more than this zone). Applies are limited to one per domain every 10 seconds; dry runs are not limited.
+
+- Params: `Mail.DomainDnsRecordApplyParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_ZONE`, `PROVIDER_TOKEN_REJECTED`, `PROVIDER_PERMISSION_DENIED`, `PROVIDER_ZONE_NOT_FOUND` | Validation failure; `Idempotency-Key` missing (`IDEMPOTENCY_KEY_REQUIRED`); `zone` not the domain or a parent (`INVALID_ZONE`); the provider rejected the token (`PROVIDER_TOKEN_REJECTED`), the token lacks DNS permissions (`PROVIDER_PERMISSION_DENIED`), or it cannot see a zone for the domain (`PROVIDER_ZONE_NOT_FOUND`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Missing `mail.update`, or the mail service is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `DNS_CONFLICTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `DNS_CONFLICTS`: a blocking conflict (a second SPF record, a CNAME at the name, another DKIM key at our selector, other MX records at the MAIL FROM host or the domain, a merge over 10 SPF lookups). Nothing was written; the body carries the full `plan` and `conflicts`. Or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Applied less than 10 seconds ago (`RATE_LIMITED`). Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+| 502 | `InternalServerError` | `BAD_GATEWAY`, `PROVIDER_UNAVAILABLE`, `PROVIDER_ERROR` | The provider failed or did not answer (`PROVIDER_UNAVAILABLE`, `PROVIDER_ERROR`). Nothing was written unless the plan items say so. |
+
+```ts
+const dnsApplyResult = await mail.domains.dnsRecords.apply("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { dry_run: true, provider: "cloudflare", token: "dop_v1_EXAMPLE_TOKEN_DO_NOT_USE" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-domains-domain-id-dns-records-apply)
+
+### `mail.domains.dnsRecords.check(domainId, params?, options?)`
+
+`POST /v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/check` → `Mail.DomainDnsRecords`
+
+Check the domain's DNS records now.
+
+Queries the zone's authoritative nameservers and a public resolver for every record, stores the result, flips a pending domain whose required records pass to `active`, and returns the same body as `GET .../dns-records`. Never fails because records are missing: their states say so. Limited to one call per domain every 10 seconds. Safe to retry: it changes nothing but the stored check result, so it takes no Idempotency-Key.
+
+- Params: `Mail.DomainDnsRecordCheckParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `INVALID_ZONE` | `zone` is not the domain or one of its parents (`INVALID_ZONE`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Checked less than 10 seconds ago (`RATE_LIMITED`). Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const domainDnsRecords = await mail.domains.dnsRecords.check("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-domains-domain-id-dns-records-check)
+
+### `mail.domains.dnsRecords.export(domainId, params, options?)`
+
+`GET /v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/export` → `Response`
+
+Download the domain's DNS records as a BIND zone fragment or a CSV.
+
+`format=bind`: a zone-file fragment (`$ORIGIN <zone>.`, `$TTL 3600`, names relative to the zone, MX with priority, TXT split into ≤255-byte quoted strings, a comment per record with its purpose, required/recommended and any conflict) that Cloudflare and Route 53 import directly. `format=csv`: `type,name,value,priority,ttl,purpose,required` (the common DNS-import columns plus two), RFC 4180 quoting, fully qualified names. By default only records not yet verified; `all=true` for every record. Served as an attachment.
+
+- Params: `Mail.DomainDnsRecordExportParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `format` missing or not `bind`/`csv`, or `zone` is not the domain or one of its parents. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const response = await mail.domains.dnsRecords.export("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { format: "bind" });
+const text = await response.text();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-domains-domain-id-dns-records-export)
+
+### `mail.domains.dnsRecords.list(domainId, params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records` → `Mail.DomainDnsRecords`
+
+Per-record DNS status for a domain.
+
+Every record the domain needs for its intent, with its state (`missing`, `mismatch`, `conflict`, `propagating`, `verified`), what was found, a propagation hint and timestamps, as of the last check (the verifier re-checks pending domains every 5 minutes and active ones hourly). Does not run a DNS lookup; use `POST .../dns-records/check` for that.
+
+- Params: `Mail.DomainDnsRecordListParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `INVALID_ZONE` | `zone` is not the domain or one of its parents (`INVALID_ZONE`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const domainDnsRecords = await mail.domains.dnsRecords.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-domains-domain-id-dns-records)
+
+## domains.domainConnect
+
+### `mail.domains.domainConnect.start(domainId, params?, options?)`
+
+`POST /v1/workspaces/{workspace_id}/domains/{domain_id}/domain-connect/start` → `Mail.DomainConnectStart`
+
+Start one-click DNS setup at the domain's DNS provider (Domain Connect).
+
+Returns a signed Domain Connect URL for the provider that hosts the domain's zone (Cloudflare, GoDaddy, IONOS, Vercel and the others that have onboarded ProductCraft's template). Open it in the browser: the user signs in at their provider and confirms, the provider writes the DKIM key at `productcraft._domainkey.<domain>` and the MAIL FROM records at `bounce.<domain>` (MX to the regional feedback host, SPF merged into any existing SPF there), and then redirects to `GET /v1/domain-connect/callback`, which records `setup_method = domain_connect`, checks the records and returns the user to the domain in the console. With `include_dmarc` and no DMARC policy in place yet, a second confirmation adds `v=DMARC1; p=none;` at `_dmarc.<domain>`. The URL is valid for 10 minutes and works once. ProductCraft never receives a DNS credential. For sending domains whose MAIL FROM label is `bounce` (the default). Not available while ProductCraft has Domain Connect switched off (`domain_connect.available` in `GET .../domains/lookup` says whether it is).
+
+- Params: `Mail.DomainDomainConnectStartParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure, or an id is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Missing `mail.update`, or the mail service is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `DOMAIN_CONNECT_DISABLED`, `DOMAIN_CONNECT_UNAVAILABLE`, `DOMAIN_CONNECT_NOT_SENDING`, `DOMAIN_CONNECT_MAIL_FROM_LABEL`, `DKIM_KEY_MISSING`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | One-click setup is not possible for this domain; nothing was started. `DOMAIN_CONNECT_DISABLED`: ProductCraft has not switched Domain Connect on. `DOMAIN_CONNECT_UNAVAILABLE`: the DNS provider does not run Domain Connect or has not onboarded our template (`details.reason`: `no_record`, `settings_unreachable`, `template_not_onboarded` or `lookup_failed`; `details.provider_name`). `DOMAIN_CONNECT_NOT_SENDING`: a receive-only domain. `DOMAIN_CONNECT_MAIL_FROM_LABEL`: the MAIL FROM label is not `bounce` or MAIL FROM is off. `DKIM_KEY_MISSING`: no DKIM key to publish. Or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const domainConnectStart = await mail.domains.domainConnect.start("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { include_dmarc: true });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-domains-domain-id-domain-connect-start)
+
+## domains.events
+
+### `mail.domains.events.list(domainId, params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/domains/{domain_id}/events` → `PagePromise<Mail.DomainEvent>`
+
+List a domain's events (its timeline), newest first, cursor-paginated.
+
+Added, records found, verified, degraded, failing, recovered, MAIL FROM verified, DMARC detected, check failed. An event is written only when something changed, so a domain checked every few minutes does not grow a row per check.
+
+- Params: `Mail.DomainEventListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid cursor, or `domain_id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const event of mail.domains.events.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b")) {
+  console.log(event);
+}
+const page = await mail.domains.events.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-domains-domain-id-events)
+
+## domains.shareLinks
+
+### `mail.domains.shareLinks.create(domainId, params?, options?)`
+
+`POST /v1/workspaces/{workspace_id}/domains/{domain_id}/share-links` → `Mail.CreatedShareLink`
+
+Create a share link: a read-only DNS setup page for whoever manages the domain's DNS.
+
+Returns a link (valid 1–7 days, default 7) to a public page that shows the domain name, its DNS records with copy-ready values, their live status and zone-file / CSV downloads, without an account. The page shows nothing else about the workspace. The link is shown only in this response (only its hash is stored); revoke it with `DELETE .../share-links/{link_id}`. Optionally emails it from ProductCraft to up to 5 recipients per domain per day (20 per workspace). Requires `mail.update` on the domain.
+
+- Params: `Mail.DomainShareLinkCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure: `expires_in_days` outside 1–7, more than 5 `email_to` entries, or an invalid address. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the key was used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | The daily email cap for the domain (5 recipients) or the workspace (20) would be exceeded (`RATE_LIMITED`). No link is created. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+| 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `EMAIL_UNAVAILABLE` | `EMAIL_UNAVAILABLE`: `email_to` was given but the email cap cannot be checked right now. No link is created; retry, or create it without `email_to`. |
+
+```ts
+const createdShareLink = await mail.domains.shareLinks.create("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { email_to: ["it@example.com"] });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-domains-domain-id-share-links)
+
+### `mail.domains.shareLinks.delete(domainId, linkId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/domains/{domain_id}/share-links/{link_id}` → `void`
+
+Revoke a share link.
+
+The public page and its downloads answer 404 from now on. Revoking an already revoked or expired link succeeds and changes nothing.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | An id is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain or share link not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.domains.shareLinks.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-domains-domain-id-share-links-link-id)
+
+### `mail.domains.shareLinks.list(domainId, params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/domains/{domain_id}/share-links` → `PagePromise<Mail.ShareLink>`
+
+List the domain's share links (newest first, including expired and revoked), cursor-paginated.
+
+The links themselves are not returned: they are shown once, at creation.
+
+- Params: `Mail.DomainShareLinkListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid cursor, or an id is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const shareLink of mail.domains.shareLinks.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b")) {
+  console.log(shareLink);
+}
+const page = await mail.domains.shareLinks.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-domains-domain-id-share-links)
+
+## domains.smtpConfig
+
+### `mail.domains.smtpConfig.reset(domainId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-config` → `void`
+
+Drop the per-domain override; sends from this domain fall back to the workspace default (or ProductCraft Mail's own sending).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No per-domain override to delete |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.domains.smtpConfig.reset("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-domains-domain-id-smtp-config)
+
+### `mail.domains.smtpConfig.retrieve(domainId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-config` → `Mail.GetSmtpConfig`
+
+Get the per-domain SMTP override (returns null if unset; the workspace default applies in that case).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const getSmtpConfig = await mail.domains.smtpConfig.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-domains-domain-id-smtp-config)
+
+### `mail.domains.smtpConfig.update(domainId, params, options?)`
+
+`PUT /v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-config` → `Mail.SmtpConfig`
+
+Create or update the per-domain SMTP override (resets verification).
+
+- Params: `Mail.DomainSmtpConfigUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure or username/password mismatch. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const smtpConfig = await mail.domains.smtpConfig.update("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", {
+  from_email: "noreply@acme.com",
+  from_name: "Acme Notifications",
+  host: "smtp.sendgrid.net",
+  port: 587,
+  secure: false,
+});
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#put-v1-workspaces-workspace-id-domains-domain-id-smtp-config)
+
+### `mail.domains.smtpConfig.verifySaved(domainId, options?)`
+
+`POST /v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-config/verify-saved` → `Mail.SmtpVerifyResult`
+
+Test the per-domain SMTP override; updates status.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No per-domain override saved |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const smtpVerifyResult = await mail.domains.smtpConfig.verifySaved("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-domains-domain-id-smtp-config-verify-saved)
+
+## emails
+
+### `mail.emails.batch(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/emails/batch` → `Mail.SendBatchOpenApi`
+
+Send up to 100 emails in one request.
+
+Each row is a `POST /emails` body plus an optional `idempotency_key`, processed independently: the response reports `accepted` (with the email `id`) or `rejected` (with `error.code`) per row. An `Idempotency-Key` header covers the whole request; a row `idempotency_key` covers one row, in the same dedupe namespace (so the header must differ from every row key).
+
+- Params: `Mail.EmailBatchParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `IDEMPOTENCY_KEY_CONFLICTS_WITH_ROW` | Validation failure (malformed row, more than 100 rows), or `IDEMPOTENCY_KEY_CONFLICTS_WITH_ROW`: the `Idempotency-Key` header equals a row `idempotency_key`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `from_domain_not_verified`, `domain_not_verified_by_provider`, `INVALID_FROM_ADDRESS` | For any row: `from_domain_not_verified` (body `code`, `details: { fqdn, reason }`): the domain of the From address is not itself an active sending domain of this workspace (`reason: not_registered` or `not_verified`); refused before anything is recorded or queued. Or `domain_not_verified_by_provider`: the from-domain's DNS records have been broken for over 72 h, so the email provider no longer sends for it. Or `INVALID_FROM_ADDRESS`. The whole batch is refused; no row is sent. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | The workspace send limits never 429 a batch: a row over one is rejected in the 200 body with `RATE_LIMITED`, and the other rows are unaffected. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const sendBatchOpenApi = await mail.emails.batch({
+  emails: [{ from: "Acme <hello@mail.acme.com>", to: ["success@simulator.amazonses.com"] }],
+});
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-emails-batch)
+
+### `mail.emails.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/emails` → `PagePromise<Mail.Email>`
+
+List emails.
+
+One entry per email (send call), newest first, with its recipients and `last_event`, the worst status across its messages. Filter by tags with `tag[name]=value` (repeat for several; all must match). Emails sent before 2026-11-06 appear as one-recipient emails.
+
+- Params: `Mail.EmailListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid cursor or tag filter. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const email of mail.emails.list()) {
+  console.log(email);
+}
+const page = await mail.emails.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-emails)
+
+### `mail.emails.metrics(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/emails/metrics` → `Mail.EmailMetrics`
+
+Email metrics for a workspace.
+
+Outbound email counts and rates over a range of up to 30 days, in hourly or daily buckets in your time zone, optionally per sending domain, filtered by domain, API key or source. Read-only.
+
+- **Emails** (`sent`): messages that left the queue.
+- **Deliverability rate**: delivered / emails sent with delivery tracking. Emails sent before delivery tracking started, or through a custom SMTP relay, are confirmed at hand-off only, so for them `delivered` is not measured and the rate is `null` (`measured.delivery = false`), never 0.
+- **Bounce rate**: bounced / emails. Suppressed recipients never count.
+- **Complaint rate**: complained / delivered, from mailbox providers' feedback loops.
+
+Rates are numbers from 0 to 1, or `null` when unmeasured or when the denominator is zero. Template test sends are excluded. Cached for up to 60 seconds.
+
+- Params: `Mail.EmailMetricsParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A parameter is invalid: `domain_id` or `api_key_id` is not a UUID; more than 100 `domain_id`; an unknown `timezone`, `granularity`, `source` or dimension; a date that does not parse; `end_date` not after `start_date`; a range longer than 30 days or starting before the 30-day retention; or `granularity=hourly` over more than 7 days. The reason is in `message`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | No valid credential. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `mail.message.read` on the workspace (including non-members), or Mail is not enabled on it (`SERVICE_NOT_ENABLED`). |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const emailMetrics = await mail.emails.metrics();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-emails-metrics)
+
+### `mail.emails.retrieve(id, options?)`
+
+`GET /v1/workspaces/{workspace_id}/emails/{id}` → `Mail.EmailDetail`
+
+Retrieve an email.
+
+The email as sent (from, to, cc, bcc, reply_to, subject, tags, custom headers) with one entry per recipient message and `last_event`, the worst status across them. Bodies are on `GET /messages/{id}/body`.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `EMAIL_NOT_FOUND` | `EMAIL_NOT_FOUND`: no email with this id in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const emailDetail = await mail.emails.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-emails-id)
+
+### `mail.emails.send(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/emails` → `Mail.SendEmail`
+
+Send an email.
+
+Send your own `html` and/or `text`, or a saved `template`, to up to 50 recipients across `to`, `cc` and `bcc`, with `reply_to`, custom `headers` and `tags`. Every recipient gets its own copy (its own message in `GET /messages`, suppression check and delivery status) showing the same `To` and `Cc` headers; `bcc` recipients appear in no header. A recipient on the suppression list (or unsubscribed, for a template with an unsubscribe link) is left out with a `suppressed` message, and the email is still accepted. Counts one send per recipient against the workspace limits. Pass an `Idempotency-Key` header to make retries safe.
+
+- Params: `Mail.EmailSendParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `EMAIL_CONTENT_CONFLICT`, `RECIPIENT_LIMIT`, `MAIL_HEADER_NOT_ALLOWED` | Validation failure; `EMAIL_CONTENT_CONFLICT` (both or neither of `html`/`text` and `template`); `RECIPIENT_LIMIT` (more than 50 recipients); `MAIL_HEADER_NOT_ALLOWED` (`details.headers` names the refused headers). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `TEMPLATE_NOT_FOUND` | `TEMPLATE_NOT_FOUND`: the `template.name` is not a template of this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `from_domain_not_verified`, `domain_not_verified_by_provider`, `INVALID_FROM_ADDRESS`, `TEMPLATE_RENDER_FAILED`, `TEMPLATE_DATA_INVALID` | `from_domain_not_verified` (body `code`, `details: { fqdn, reason }`): the domain of the From address is not itself an active sending domain of this workspace (`reason: not_registered` or `not_verified`); refused before anything is recorded or queued. Or `domain_not_verified_by_provider`: the from-domain's DNS records have been broken for over 72 h, so the email provider no longer sends for it. Or `INVALID_FROM_ADDRESS`. Or `TEMPLATE_RENDER_FAILED` / `TEMPLATE_DATA_INVALID` for a template send. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Over a workspace send limit (60 per minute, 600 per hour, 10,000 per day; each recipient counts): `RATE_LIMITED` with `details: { window, limit, retry_after }`. Nothing is recorded or queued. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const sendEmail = await mail.emails.send({ from: "Acme <hello@mail.acme.com>", to: ["success@simulator.amazonses.com"] });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-emails)
+
+## integrations
+
+### `mail.integrations.delete(provider, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/integrations/{provider}` → `void`
+
+Disconnect an integration. Deletes the credential row.
+
+Hard delete — the encrypted blob is removed. The customer must reconnect via the provider-specific OAuth flow to restore access.
+
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.integrations.delete("provider");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-integrations-provider)
+
+### `mail.integrations.list(options?)`
+
+`GET /v1/workspaces/{workspace_id}/integrations` → `Mail.ListIntegrations`
+
+List connected workspace integrations.
+
+Returns one entry per connected provider (GitHub, …). No secrets in the response — only public identifiers + status + sync stamps.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const listIntegrations = await mail.integrations.list();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-integrations)
+
+### `mail.integrations.retrieve(provider, options?)`
+
+`GET /v1/workspaces/{workspace_id}/integrations/{provider}` → `Mail.IntegrationDetail`
+
+Get a single integration detail with redacted credentials.
+
+Includes the provider's `credentials_redacted` view. Secret fields (access tokens, signing keys) are never included.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No integration of the requested provider for this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const integrationDetail = await mail.integrations.retrieve("provider");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-integrations-provider)
+
+## integrations.github
+
+### `mail.integrations.github.connect(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/integrations/github/connect` → `Mail.ConnectGitHub`
+
+Mint a GitHub OAuth state token and return the authorize URL.
+
+The frontend redirects the user to `authorize_url`; GitHub bounces back to the `/callback` endpoint with a `code` + `state` pair. state is single-use, 5-minute TTL.
+
+- Params: `Mail.IntegrationGithubConnectParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const connectGitHub = await mail.integrations.github.connect({ return_to: "https://console.productcraft.co/mail/workspaces/acme/integrations" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-integrations-github-connect)
+
+## integrations.github.repos
+
+### `mail.integrations.github.repos.list(options?)`
+
+`GET /v1/workspaces/{workspace_id}/integrations/github/repos` → `Mail.IntegrationGithubRepoListResponse`
+
+List repos visible to the connected GitHub account.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const result = await mail.integrations.github.repos.list();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-integrations-github-repos)
+
+## integrations.github.repos.branches
+
+### `mail.integrations.github.repos.branches.list(owner, repo, options?)`
+
+`GET /v1/workspaces/{workspace_id}/integrations/github/repos/{owner}/{repo}/branches` → `Mail.IntegrationGithubRepoBranchListResponse`
+
+List branches for the given repo.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const result = await mail.integrations.github.repos.branches.list("owner", "repo");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-integrations-github-repos-owner-repo-branches)
+
+## integrations.github.settings
+
+### `mail.integrations.github.settings.update(params, options?)`
+
+`PUT /v1/workspaces/{workspace_id}/integrations/github/settings` → `void`
+
+Set the repo + branch + templates path to sync from.
+
+- Params: `Mail.IntegrationGithubSettingsUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.integrations.github.settings.update({ branch: "main", repo_full_name: "octocat/templates", templates_path: "/" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#put-v1-workspaces-workspace-id-integrations-github-settings)
+
+## integrations.github.sync
+
+### `mail.integrations.github.sync.create(options?)`
+
+`POST /v1/workspaces/{workspace_id}/integrations/github/sync` → `Mail.StartSync`
+
+Trigger an immediate sync from GitHub. Returns a sync id to poll.
+
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const startSync = await mail.integrations.github.sync.create();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-integrations-github-sync)
+
+### `mail.integrations.github.sync.retrieve(syncId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/integrations/github/sync/{sync_id}` → `Mail.SyncStatus`
+
+Poll a sync run's status.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Run not found or expired. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const syncStatus = await mail.integrations.github.sync.retrieve("sync");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-integrations-github-sync-sync-id)
+
+## mailboxes
+
+### `mail.mailboxes.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/mailboxes` → `Mail.Mailbox`
+
+Create a mailbox under a verified domain. Local-part + domain combination must be globally unique.
+
+- Params: `Mail.MailboxCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure (invalid local part, retention out of range). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Caller lacks `mail.create` permission, or workspace has not enabled the `mail` service. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Domain not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Mailbox local-part already exists on this domain, or the domain is not yet verified, or `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different body or route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | Local part or retention rejected by service-layer validation. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const mailbox = await mail.mailboxes.create({ domain_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b", local_part: "claude-qa-alpha" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-mailboxes)
+
+### `mail.mailboxes.delete(id, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/mailboxes/{id}` → `void`
+
+Soft-delete a mailbox: its status becomes `disabled` and it stops accepting new mail; existing messages are kept until retention purges them, and `PATCH` with `status: active` restores it. A deleted mailbox no longer blocks deleting its domain, and deleting the domain erases it and its remaining mail.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Mailbox not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.mailboxes.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-mailboxes-id)
+
+### `mail.mailboxes.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/mailboxes` → `PagePromise<Mail.Mailbox>`
+
+List mailboxes in this workspace. 20 per page by default (max 200) — paginate with the cursor returned in `pagination.next_cursor` while `pagination.has_more` is true.
+
+- Params: `Mail.MailboxListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Caller lacks `mail.read` permission, or workspace has not enabled the `mail` service. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const mailbox of mail.mailboxes.list()) {
+  console.log(mailbox);
+}
+const page = await mail.mailboxes.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-mailboxes)
+
+### `mail.mailboxes.retrieve(id, options?)`
+
+`GET /v1/workspaces/{workspace_id}/mailboxes/{id}` → `Mail.Mailbox`
+
+Get one mailbox by id.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Mailbox not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const mailbox = await mail.mailboxes.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-mailboxes-id)
+
+### `mail.mailboxes.update(id, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/mailboxes/{id}` → `Mail.Mailbox`
+
+Update mailbox display name, retention, or status. Status transitions are restricted (active ↔ suspended; archived is terminal).
+
+- Params: `Mail.MailboxUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure or invalid status transition. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Mailbox not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | Retention or status rejected by service-layer validation. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const mailbox = await mail.mailboxes.update("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { display_name: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-mailboxes-id)
+
+## mailboxes.messages
+
+### `mail.mailboxes.messages.delete(id, mid, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}` → `void`
+
+Soft-delete a message.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Message not found |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.mailboxes.messages.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-mailboxes-id-messages-mid)
+
+### `mail.mailboxes.messages.list(id, params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/mailboxes/{id}/messages` → `PagePromise<Mail.Message>`
+
+List messages in a mailbox.
+
+- Params: `Mail.MailboxMessageListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid filter or cursor. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Mailbox not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const message of mail.mailboxes.messages.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b")) {
+  console.log(message);
+}
+const page = await mail.mailboxes.messages.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-mailboxes-id-messages)
+
+### `mail.mailboxes.messages.raw(id, mid, options?)`
+
+`GET /v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}/raw` → `Response`
+
+Stream the raw RFC5322 .eml for a message. Gated by `mail.message.body.read` (admin+ by default; not granted to plain members) — the outbound lane's /messages/:id/body action.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Policy denies `mail.message.body.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Message not found |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const response = await mail.mailboxes.messages.raw("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+const text = await response.text();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-mailboxes-id-messages-mid-raw)
+
+### `mail.mailboxes.messages.read(id, mid, options?)`
+
+`POST /v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}/read` → `void`
+
+Mark a message as read.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Message not found |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.mailboxes.messages.read("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-mailboxes-id-messages-mid-read)
+
+### `mail.mailboxes.messages.retrieve(id, mid, options?)`
+
+`GET /v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}` → `Mail.MessageDetail`
+
+Get a single message (metadata + attachment manifest; `body_preview` is null without `mail.message.body.read`). Use /:mid/raw for content.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Message not found |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const messageDetail = await mail.mailboxes.messages.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-mailboxes-id-messages-mid)
+
+## mailboxes.messages.attachments
+
+### `mail.mailboxes.messages.attachments.retrieve(id, mid, position, options?)`
+
+`GET /v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}/attachments/{position}` → `Response`
+
+Stream a single attachment by its position. Gated by `mail.message.body.read`: an attachment is message content, and /:mid already names it without handing over the bytes.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | Policy denies `mail.message.body.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Attachment not found |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const response = await mail.mailboxes.messages.attachments.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "5d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6", "position");
+const text = await response.text();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-mailboxes-id-messages-mid-attachments-position)
+
+## messages
+
+### `mail.messages.body(id, options?)`
+
+`GET /v1/workspaces/{workspace_id}/messages/{id}/body` → `Mail.OutboundMessageWithBody`
+
+Get the cleartext body of an outbound message. Gated by `mail.message.body.read` (admin+ by default; not granted to plain members).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Not found. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const outboundMessageWithBody = await mail.messages.body("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-messages-id-body)
+
+### `mail.messages.erase(params, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/messages` → `Mail.DeleteByRecipient`
+
+RTBF: delete every message log row for `recipient` (case-insensitive). Returns the deleted-row count.
+
+The bulk GDPR erase (`messages.erase` in the SDKs): removes every delivery-log row sent to one recipient address in this workspace (with its stored body and events), and strips the address from the cc, bcc and reply-to lists of other rows, in one transaction. Repeating it is harmless (the second call deletes 0 rows).
+
+- Params: `Mail.MessageEraseParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Missing or invalid recipient. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const deleteByRecipient = await mail.messages.erase({ recipient: "ada@example.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-messages)
+
+### `mail.messages.export(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/messages/export` → `Response`
+
+Stream the filtered message log as CSV. Same filters as GET /messages. Body columns are intentionally omitted; bodies remain gated by `mail.message.body.read`. Rate-limited 1 concurrent + 5/hour per workspace.
+
+Columns: id, created_at, sent_at, delivered_at, deferred_at, deferral_count, from_address, to_address, subject, template_name, status, spf_result, dkim_result, dmarc_result, bounce_code, bounce_detail, api_key_id, source, domain. The filters are resolved by the same code as `GET /messages`, so the same query string exports exactly the rows the list pages through. A rejected filter (400) does not count against the hourly cap.
+
+- Params: `Mail.MessageExportParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid filter: an unknown status or source, a malformed uuid or date-time, `q` over 200 characters, `created_after` not earlier than `created_before`, or a window wider than 30 days. The reason is in `message`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Another export is already running, or this workspace has hit the hourly export cap. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const response = await mail.messages.export();
+const text = await response.text();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-messages-export)
+
+### `mail.messages.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/messages` → `PagePromise<Mail.OutboundMessage>`
+
+List outbound messages with cursor pagination.
+
+One row per recipient delivery, newest first. Filters combine with AND: `q` (free text over recipient, from, subject, message id and Message-ID), `status` (any of, repeatable), `domain_id`, `api_key_id`, `source`, `template`, `created_after` / `created_before` (at most 30 days apart), plus the legacy `recipient` and `subject_contains`. `GET /messages/export` takes exactly the same filters and returns the same rows.
+
+- Params: `Mail.MessageListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid filter or cursor: an unknown status or source, a malformed uuid or date-time, `q` over 200 characters, `created_after` not earlier than `created_before`, or a window wider than 30 days. The reason is in `message`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const message of mail.messages.list()) {
+  console.log(message);
+}
+const page = await mail.messages.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-messages)
+
+### `mail.messages.retrieve(id, options?)`
+
+`GET /v1/workspaces/{workspace_id}/messages/{id}` → `Mail.OutboundMessageDetail`
+
+Get a single outbound message (metadata + delivery verdicts; body not included) with its event timeline: `events[]` oldest first, `last_event`, `transport`, `bounce_type`, `bounce_subtype`. Use /:id/body for cleartext content.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Not found. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const outboundMessageDetail = await mail.messages.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-messages-id)
+
+### `mail.messages.timeline(params, options?)`
+
+`GET /v1/workspaces/{workspace_id}/messages/timeline` → `Mail.MessageTimeline`
+
+Day-bucketed inbound message volume for a workspace.
+
+Counts INBOUND mail only: messages received by the workspace's mailboxes, in dense day buckets in [since, until). `metric=sent` (default, a historical name) counts received messages, not outbound sends; `metric=bounced` counts MX-time rejections matched to this workspace by envelope-to. For outbound counts and rates use `GET /emails/metrics`.
+
+- Params: `Mail.MessageTimelineParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const messageTimeline = await mail.messages.timeline({ granularity: "day", since: "2026-04-01T00:00:00Z", until: "2026-05-01T00:00:00Z" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-messages-timeline)
+
+## messages.settings
+
+### `mail.messages.settings.retrieve(options?)`
+
+`GET /v1/workspaces/{workspace_id}/messages/settings` → `Mail.OutboundMessageSettings`
+
+Read this workspace's outbound-message settings. Absent → defaults (redact_bodies: false).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const outboundMessageSettings = await mail.messages.settings.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-messages-settings)
+
+### `mail.messages.settings.update(params, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/messages/settings` → `Mail.OutboundMessageSettings`
+
+Update this workspace's outbound-message settings. Gated on `mail.message.delete` — same privilege bar as RTBF, since both touch the PII boundary.
+
+- Params: `Mail.MessageSettingsUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid payload. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const outboundMessageSettings = await mail.messages.settings.update({ redact_bodies: true });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-messages-settings)
+
+## received
+
+### `mail.received.delete(id, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/received/{id}` → `void`
+
+Delete a received email.
+
+Soft delete: it disappears from every list at once; retention purges the stored message later.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `id` is not a uuid. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The policy does not grant `mail.delete` on every mailbox. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such email in this workspace (or it was already deleted). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.received.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-received-id)
+
+### `mail.received.export(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/received/export` → `Response`
+
+Stream the filtered received email as CSV. Same filters as GET /received. Rate-limited 1 concurrent + 5/hour per workspace.
+
+Columns: id, received_at, mailbox, from, to (`; `-separated), subject, spam_verdict, spf, dkim, dmarc, size_bytes, attachments (count). No body content. A cell starting with `=`, `+`, `-` or `@` is prefixed with `'` so a spreadsheet does not run it as a formula. A rejected filter (400) does not count against the hourly cap, which is separate from the sent-email export's.
+
+- Params: `Mail.ReceivedExportParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid filter or cursor: a malformed uuid, boolean or date-time, `q` over 200 characters, `received_after` not earlier than `received_before`, or a window wider than 30 days. The reason is in `message`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The policy does not grant `mail.list` on every mailbox, or Mail is not enabled for this workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Another received-email export is already running, or this workspace has hit the hourly cap (5). Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const response = await mail.received.export();
+const text = await response.text();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-received-export)
+
+### `mail.received.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/received` → `PagePromise<Mail.ReceivedEmail>`
+
+List received email across every mailbox in the workspace.
+
+Newest first, cursor-paged, deleted email excluded. Filters combine with AND: `q` (sender, subject, envelope recipient or To address as a substring; or an exact id or Message-ID), `mailbox_id`, `domain_id`, `received_after` / `received_before` (at most 30 days apart), `spam`, `unread`. `GET /received/export` takes exactly the same filters and returns the same rows. No body content.
+
+- Params: `Mail.ReceivedListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid filter or cursor: a malformed uuid, boolean or date-time, `q` over 200 characters, `received_after` not earlier than `received_before`, or a window wider than 30 days. The reason is in `message`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The policy does not grant `mail.list` on every mailbox, or Mail is not enabled for this workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const received of mail.received.list()) {
+  console.log(received);
+}
+const page = await mail.received.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-received)
+
+### `mail.received.raw(id, options?)`
+
+`GET /v1/workspaces/{workspace_id}/received/{id}/raw` → `Response`
+
+Download the raw RFC 5322 message (.eml).
+
+Every header, the full body and every attachment inline. Gated by `mail.message.body.read` (admin and up by default), like `/mailboxes/{id}/messages/{mid}/raw`.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `id` is not a uuid. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The policy does not grant `mail.message.body.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such email in this workspace (or it was deleted). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const response = await mail.received.raw("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+const text = await response.text();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-received-id-raw)
+
+### `mail.received.read(id, options?)`
+
+`POST /v1/workspaces/{workspace_id}/received/{id}/read` → `void`
+
+Mark a received email as read.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `id` is not a uuid. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The policy does not grant `mail.read` on every mailbox. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such email in this workspace (or it was deleted). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.received.read("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-received-id-read)
+
+### `mail.received.retrieve(id, options?)`
+
+`GET /v1/workspaces/{workspace_id}/received/{id}` → `Mail.ReceivedEmailDetail`
+
+Get one received email.
+
+Metadata, the authentication results, the envelope recipient and the attachment manifest. `body_preview` is null without `mail.message.body.read`; the full message is at `/received/{id}/raw`.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `id` is not a uuid. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The policy does not grant `mail.read` on every mailbox. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such email in this workspace (or it was deleted). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const receivedEmailDetail = await mail.received.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-received-id)
+
+## received.attachments
+
+### `mail.received.attachments.retrieve(id, position, options?)`
+
+`GET /v1/workspaces/{workspace_id}/received/{id}/attachments/{position}` → `Response`
+
+Download one attachment of a received email.
+
+By its `position` from the detail's attachment manifest. Unscanned, untrusted bytes from a third party. Gated by `mail.message.body.read`.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `id` is not a uuid or `position` is not an integer. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The policy does not grant `mail.message.body.read`. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No such email in this workspace, or no attachment at that position. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const response = await mail.received.attachments.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "position");
+const text = await response.text();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-received-id-attachments-position)
+
+## segments
+
+### `mail.segments.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/segments` → `Mail.Segment`
+
+Create a segment.
+
+Without `rule`, a static segment: add and remove contacts one at a time. With `rule`, a rule segment: its members are the contacts whose fields and properties match, evaluated every time it is read. At most 100 segments per workspace.
+
+- Params: `Mail.SegmentCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `SEGMENT_EXISTS`, `SEGMENT_LIMIT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | A segment with this name exists (`SEGMENT_EXISTS`), the workspace has 100 segments (`SEGMENT_LIMIT`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_SEGMENT_RULE` | The rule is invalid (`INVALID_SEGMENT_RULE`; `details.problems` lists each one with its condition index): an unknown field, `contains` on a number property, a missing or mistyped `value`, a `value` on `exists`. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const segment = await mail.segments.create({ name: "Pro customers" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-segments)
+
+### `mail.segments.delete(segmentId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/segments/{segment_id}` → `void`
+
+Delete a segment.
+
+Contacts are not touched; a static segment's member list goes with it.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | No such segment (`SEGMENT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.segments.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-segments-segment-id)
+
+### `mail.segments.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/segments` → `PagePromise<Mail.Segment>`
+
+List segments, newest first.
+
+- Params: `Mail.SegmentListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const segment of mail.segments.list()) {
+  console.log(segment);
+}
+const page = await mail.segments.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-segments)
+
+### `mail.segments.metrics(segmentId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/segments/{segment_id}/metrics` → `Mail.SegmentMetrics`
+
+A segment's size and unsubscribed share.
+
+Counted on request.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | No such segment (`SEGMENT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const segmentMetrics = await mail.segments.metrics("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-segments-segment-id-metrics)
+
+### `mail.segments.preview(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/segments/preview` → `Mail.SegmentPreview`
+
+Preview a segment rule.
+
+Counts the contacts a rule selects and returns the newest few, without saving anything.
+
+- Params: `Mail.SegmentPreviewParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_SEGMENT_RULE` | The rule is invalid (`INVALID_SEGMENT_RULE`; `details.problems` lists each one with its condition index): an unknown field, `contains` on a number property, a missing or mistyped `value`, a `value` on `exists`. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const segmentPreview = await mail.segments.preview({ rule: { conditions: [{ field: "plan", operator: "equals" }], match: "all" } });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-segments-preview)
+
+### `mail.segments.retrieve(segmentId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/segments/{segment_id}` → `Mail.Segment`
+
+Get a segment.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | No such segment (`SEGMENT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const segment = await mail.segments.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-segments-segment-id)
+
+### `mail.segments.update(segmentId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/segments/{segment_id}` → `Mail.Segment`
+
+Update a segment.
+
+Rename it, or change a rule segment's rule. A segment's type (static or rule) is fixed.
+
+- Params: `Mail.SegmentUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | No such segment (`SEGMENT_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `SEGMENT_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Another segment has this name (`SEGMENT_EXISTS`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_SEGMENT_RULE`, `SEGMENT_TYPE_FIXED` | The rule is invalid (`INVALID_SEGMENT_RULE`; `details.problems` lists each one with its condition index): an unknown field, `contains` on a number property, a missing or mistyped `value`, a `value` on `exists`. Or a rule on a static segment (`SEGMENT_TYPE_FIXED`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const segment = await mail.segments.update("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { description: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-segments-segment-id)
+
+## segments.contacts
+
+### `mail.segments.contacts.list(segmentId, params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/segments/{segment_id}/contacts` → `PagePromise<Mail.Contact>`
+
+List a segment's contacts.
+
+Newest contact first. For a rule segment, the contacts matching its rule right now.
+
+- Params: `Mail.SegmentContactListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | No such segment (`SEGMENT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const contact of mail.segments.contacts.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b")) {
+  console.log(contact);
+}
+const page = await mail.segments.contacts.list("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", {}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-segments-segment-id-contacts)
+
+## sendingDefaults
+
+### `mail.sendingDefaults.retrieve(options?)`
+
+`GET /v1/workspaces/{workspace_id}/sending-defaults` → `Mail.SendingDefaults`
+
+Get the workspace default sender.
+
+The From used by template sends that name none, with the live verification status of its domain. `default_sender` is null when none is set.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const sendingDefaults = await mail.sendingDefaults.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-sending-defaults)
+
+### `mail.sendingDefaults.update(params, options?)`
+
+`PUT /v1/workspaces/{workspace_id}/sending-defaults` → `Mail.SendingDefaults`
+
+Set or clear the workspace default sender.
+
+Replaces the default sender (`address: null` clears it). The change applies to the next send of every product at once, and emits a `sending_defaults.updated` webhook event. Repeating the same request changes nothing, so it takes no `Idempotency-Key`.
+
+- Params: `Mail.SendingDefaultUpdateParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `sender_domain_not_in_workspace`, `INVALID_FROM_ADDRESS` | `sender_domain_not_in_workspace` (`details: { fqdn }`): the address is not on a sending domain of this workspace (unknown, another workspace's, or receive-only). `INVALID_FROM_ADDRESS`: the address could not be parsed. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const sendingDefaults = await mail.sendingDefaults.update({ address: "Acme <hello@acme.com>" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#put-v1-workspaces-workspace-id-sending-defaults)
+
+## smtpConfig
+
+### `mail.smtpConfig.list(options?)`
+
+`GET /v1/workspaces/{workspace_id}/smtp-configs` → `Mail.ListSmtpConfigs`
+
+List every SMTP config in the workspace (default + per-domain overrides).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const listSmtpConfigs = await mail.smtpConfig.list();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-smtp-configs)
+
+### `mail.smtpConfig.reset(options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/smtp-config` → `void`
+
+Revert the workspace to ProductCraft Mail's own sending.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No SMTP config to delete |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.smtpConfig.reset();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-smtp-config)
+
+### `mail.smtpConfig.retrieve(options?)`
+
+`GET /v1/workspaces/{workspace_id}/smtp-config` → `Mail.GetSmtpConfig`
+
+Get the workspace-default SMTP config (returns null if unset). Per-domain overrides live under /workspaces/:id/domains/:domainId/smtp-config.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const getSmtpConfig = await mail.smtpConfig.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-smtp-config)
+
+### `mail.smtpConfig.update(params, options?)`
+
+`PUT /v1/workspaces/{workspace_id}/smtp-config` → `Mail.SmtpConfig`
+
+Create or update the workspace-default SMTP config (resets verification).
+
+- Params: `Mail.SmtpConfigUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure or username/password mismatch. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const smtpConfig = await mail.smtpConfig.update({
+  from_email: "noreply@acme.com",
+  from_name: "Acme Notifications",
+  host: "smtp.sendgrid.net",
+  port: 587,
+  secure: false,
+});
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#put-v1-workspaces-workspace-id-smtp-config)
+
+### `mail.smtpConfig.verify(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/smtp-config/verify` → `Mail.SmtpVerifyResult`
+
+Test arbitrary SMTP creds without persisting.
+
+- Params: `Mail.SmtpConfigVerifyParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure on the request body. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const smtpVerifyResult = await mail.smtpConfig.verify({
+  from_email: "noreply@acme.com",
+  from_name: "Acme Notifications",
+  host: "smtp.sendgrid.net",
+  port: 587,
+  secure: false,
+});
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-smtp-config-verify)
+
+### `mail.smtpConfig.verifySaved(options?)`
+
+`POST /v1/workspaces/{workspace_id}/smtp-config/verify-saved` → `Mail.SmtpVerifyResult`
+
+Test the persisted workspace-default SMTP config; updates status.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | No SMTP config saved |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const smtpVerifyResult = await mail.smtpConfig.verifySaved();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-smtp-config-verify-saved)
+
+## stats
+
+### `mail.stats.retrieve(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/stats` → `Mail.MailWorkspaceStats`
+
+Mail stats for a workspace.
+
+Outbound sent, delivered, bounced, complained, deferred, suppressed and unconfirmed counts in the window, the deliverability, bounce and complaint rates, domain totals, the last send time and a daily sent series. For ranges, buckets, filters and a per-domain breakdown use `GET /emails/metrics`; the rates here use its definitions.
+
+`delivered` means the recipient's mail server confirmed the message; `unconfirmed` means the message was handed off and nothing came back either way, which is not the same as delivered. Days are UTC. Rates are 0 to 1, or null when not measured: delivery and complaints are only reported for mail with delivery tracking. Outbound messages are kept for 30 days, so 30d is the longest window. Cached for up to 60 seconds (`generated_at`).
+
+- Params: `Mail.StatsRetrieveParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `window` is not one of 1d, 7d, 30d. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `mail.message.read` on the workspace (including non-members), or Mail is not enabled on it (`SERVICE_NOT_ENABLED`). |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const mailWorkspaceStats = await mail.stats.retrieve();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-stats)
+
+## suppression
+
+### `mail.suppression.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/suppression` → `Mail.SuppressionEntry`
+
+Add an email to the workspace suppression list.
+
+- Params: `Mail.SuppressionCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid payload (missing or malformed email). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | Email address rejected as invalid by the service layer. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const suppressionEntry = await mail.suppression.create({ email: "bounced@example.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-suppression)
+
+### `mail.suppression.delete(email, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/suppression/{email}` → `void`
+
+Remove an address from the workspace suppression list.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Email is not on this workspace suppression list. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.suppression.delete("email");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-suppression-email)
+
+### `mail.suppression.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/suppression` → `PagePromise<Mail.SuppressionEntry>`
+
+List suppressed recipients in the workspace (most-recent first), cursor-paginated.
+
+- Params: `Mail.SuppressionListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid cursor, search term, or source filter. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const suppression of mail.suppression.list()) {
+  console.log(suppression);
+}
+const page = await mail.suppression.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-suppression)
+
+## templates
+
+### `mail.templates.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/templates` → `Mail.Template`
+
+Create or update a template, layout, or partial. Idempotent on (workspace_id, name); `kind` cannot change after the first upsert.
+
+- Params: `Mail.TemplateCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure (bad name / payload). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const template = await mail.templates.create({ body_html: "string", name: "order-confirmation", subject: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-templates)
+
+### `mail.templates.delete(name, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/templates/{name}` → `void`
+
+Delete a template, layout, or partial by name.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Template not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.templates.delete("name");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-templates-name)
+
+### `mail.templates.lint(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/templates/lint` → `Mail.LintResult`
+
+Lint a draft for deliverability red flags. Same render pipeline as /preview; returns a 0-100 score (higher is better) and a sorted list of findings (errors first). Self-developed heuristic linter, no external classifier — runs in-process.
+
+- Params: `Mail.TemplateLintParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | Underlying render failed. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const lintResult = await mail.templates.lint({ body_html: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-templates-lint)
+
+### `mail.templates.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/templates` → `PagePromise<Mail.Template>`
+
+List templates / layouts / partials in a workspace, name-ascending and cursor-paginated. Filter via ?kind=template|layout|partial (default: all), ?tags=foo,bar (comma-separated), ?search=<substring of the name>.
+
+- Params: `Mail.TemplateListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid cursor or search term. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const template of mail.templates.list()) {
+  console.log(template);
+}
+const page = await mail.templates.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-templates)
+
+### `mail.templates.preview(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/templates/preview` → `Mail.RenderedMessage`
+
+Preview an unsaved draft. Renders subject + bodyHtml against the workspace brand tokens + supplied data, with all workspace layouts/partials registered. Used by the editor for live preview.
+
+- Params: `Mail.TemplatePreviewParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | Render failed (compile or runtime error). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const renderedMessage = await mail.templates.preview({ body_html: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-templates-preview)
+
+### `mail.templates.render(name, params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/templates/{name}/render` → `Mail.RenderedMessage`
+
+Render a saved template against a data payload. Returns subject + html + text without sending.
+
+- Params: `Mail.TemplateRenderParams`
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Template not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT` | Cannot render a layout/partial — only sendable templates. |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | Render or schema validation failed. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const renderedMessage = await mail.templates.render("name", { data: { name: "Alice", order_id: "ord_123" } });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-templates-name-render)
+
+### `mail.templates.retrieve(name, options?)`
+
+`GET /v1/workspaces/{workspace_id}/templates/{name}` → `Mail.Template`
+
+Get a template, layout, or partial by name.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Template not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const template = await mail.templates.retrieve("name");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-templates-name)
+
+### `mail.templates.send(name, params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/templates/{name}/send` → `Mail.SendAccepted`
+
+Send a template-rendered message. Pass an `Idempotency-Key` header (1..256 chars, [A-Za-z0-9_\-:]) to make retries safe — replays return the original response with `Idempotent-Replay: true` for 24h. Same key + different request body returns 409 IDEMPOTENCY_KEY_REUSE.
+
+- Params: `Mail.TemplateSendParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure (malformed body or recipient). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Template not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | IDEMPOTENCY_KEY_REUSE — same key, different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `RECIPIENT_SUPPRESSED`, `TOPIC_NOT_FOUND`, `from_domain_not_verified`, `domain_not_verified_by_provider`, `no_default_sender` | Recipient suppressed (`RECIPIENT_SUPPRESSED`; with a `topic_id`, or a template rendering `{{{unsubscribe_url}}}`, also when the recipient unsubscribed or never opted in: `details.reason` is `unsubscribe` or `no_consent`), `TOPIC_NOT_FOUND`, render failure, or invalid from address; or `from_domain_not_verified` (body `code`, `details: { fqdn, reason }`): the domain of the From address is not itself an active sending domain of this workspace — `reason: not_registered` (unknown, registered to another workspace, or only a subdomain such as `mail.example.com` is verified; a verified subdomain does not cover its parent) or `reason: not_verified` (registered, DNS not verified yet). Refused before anything is recorded or queued; or `domain_not_verified_by_provider` (body `code`): the from-domain's DNS records have been broken for over 72 h (`health: failing`), so the email provider no longer sends for it; or `no_default_sender` (body `code`): the body has no `from` and the workspace has no default sender set (nothing is queued; an `email.skipped` webhook event is logged). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Over a workspace send limit (60 per minute, 600 per hour, 10,000 per day): `RATE_LIMITED` with `details: { window, limit, retry_after }`. Nothing is recorded or queued. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const sendAccepted = await mail.templates.send("name", { data: { name: "Alice", order_id: "ord_123" }, to: "user@example.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-templates-name-send)
+
+### `mail.templates.sendBatch(name, params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/templates/{name}/send-batch` → `Mail.SendBatchOpenApi`
+
+Send up to 100 messages with the same template in one request. Per-row partial-success: each row carries its own status (`accepted` | `rejected`).
+
+Two ways to make retries safe. An `Idempotency-Key` header covers the whole request: a retry with the same key and body within 24 h returns the first response (with `Idempotent-Replay: true`) and sends nothing. A per-row `idempotency_key` covers one message: a later batch, or a `/send`, that repeats a row key replays that row instead of sending it again. Both share one dedupe namespace, so the header key must differ from every row key (400 otherwise).
+
+- Params: `Mail.TemplateSendBatchParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `IDEMPOTENCY_KEY_CONFLICTS_WITH_ROW` | Validation failure (malformed body, batch too large), or the `Idempotency-Key` header equals a row `idempotency_key` (`IDEMPOTENCY_KEY_CONFLICTS_WITH_ROW`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Template not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different request body or on a different route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `from_domain_not_verified`, `domain_not_verified_by_provider` | For any row: `from_domain_not_verified` (body `code`, `details: { fqdn, reason }`): the domain of the From address is not itself an active sending domain of this workspace — `reason: not_registered` (unknown, registered to another workspace, or only a subdomain such as `mail.example.com` is verified; a verified subdomain does not cover its parent) or `reason: not_verified` (registered, DNS not verified yet). Refused before anything is recorded or queued (the whole batch is refused); or `domain_not_verified_by_provider` (body `code`): the from-domain's DNS records have been broken for over 72 h (`health: failing`), so the email provider no longer sends for it. The whole batch is refused; no row is sent. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | The workspace send limits (60 per minute, 600 per hour, 10,000 per day) never 429 a batch: a row over one is rejected in the 200 body with `RATE_LIMITED`, and the other rows are unaffected. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const sendBatchOpenApi = await mail.templates.sendBatch("name", {
+  messages: [
+    {
+      data: { code: "A1B2C3", name: "Alice" },
+      from: "Acme <noreply@acme.com>",
+      to: "alice@example.com",
+    },
+  ],
+});
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-templates-name-send-batch)
+
+### `mail.templates.testSend(name, params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/templates/{name}/test-send` → `Mail.SendAccepted`
+
+Send a test rendering of the template to an arbitrary recipient. Bypasses the suppression list and the ordinary send limits (test sends have their own: 30 per hour per workspace); subject is auto-prefixed with [TEST]; missing variables render as [varname] placeholders.
+
+- Params: `Mail.TemplateTestSendParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | From-address domain is not registered to this workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Template not found in this workspace. |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Cannot test-send a layout/partial, or `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different body or route. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `from_domain_not_verified`, `domain_not_verified_by_provider` | Invalid from address or render failure; or `from_domain_not_verified` (body `code`, `details: { fqdn, reason }`): the domain of the From address is not itself an active sending domain of this workspace — `reason: not_registered` (unknown, registered to another workspace, or only a subdomain such as `mail.example.com` is verified; a verified subdomain does not cover its parent) or `reason: not_verified` (registered, DNS not verified yet). Refused before anything is recorded or queued; or `domain_not_verified_by_provider` (body `code`): the from-domain's DNS records have been broken for over 72 h (`health: failing`), so the email provider no longer sends for it. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 30 test sends this hour in this workspace: `RATE_LIMITED` with `details: { window, limit, retry_after }`. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const sendAccepted = await mail.templates.testSend("name", { from: "Acme <hello@acme.com>", to: "ada@example.com" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-templates-name-test-send)
+
+## templates.tags
+
+### `mail.templates.tags.list(options?)`
+
+`GET /v1/workspaces/{workspace_id}/templates/tags` → `Mail.ListTemplateTags`
+
+Distinct tag list across all templates in this workspace (for autocomplete).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const listTemplateTags = await mail.templates.tags.list();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-templates-tags)
+
+## templates.variables
+
+### `mail.templates.variables.list(name, options?)`
+
+`GET /v1/workspaces/{workspace_id}/templates/{name}/variables` → `Mail.TemplateVariables`
+
+Variables auto-detected from the saved template body + subject (Handlebars expressions, dotted paths preserved, dedup'd in first-occurrence order).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Template not found in this workspace. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const templateVariables = await mail.templates.variables.list("name");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-templates-name-variables)
+
+## topics
+
+### `mail.topics.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/topics` → `Mail.Topic`
+
+Create a topic.
+
+Send on a topic with `topic_id` on a template send. Recipients manage their topics on the hosted unsubscribe page. At most 50 topics per workspace.
+
+- Params: `Mail.TopicCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `TOPIC_EXISTS`, `TOPIC_LIMIT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | A topic with this name exists (`TOPIC_EXISTS`), the workspace has 50 topics (`TOPIC_LIMIT`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const topic = await mail.topics.create({ default_subscription: "opt_in", name: "Product updates" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-topics)
+
+### `mail.topics.delete(topicId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/topics/{topic_id}` → `void`
+
+Delete a topic.
+
+Also deletes every contact's choice for it. Sends naming it are refused afterwards (`TOPIC_NOT_FOUND`).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `TOPIC_NOT_FOUND` | No such topic (`TOPIC_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.topics.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-topics-topic-id)
+
+### `mail.topics.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/topics` → `PagePromise<Mail.Topic>`
+
+List topics, newest first.
+
+- Params: `Mail.TopicListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const topic of mail.topics.list()) {
+  console.log(topic);
+}
+const page = await mail.topics.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-topics)
+
+### `mail.topics.retrieve(topicId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/topics/{topic_id}` → `Mail.Topic`
+
+Get a topic.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `TOPIC_NOT_FOUND` | No such topic (`TOPIC_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const topic = await mail.topics.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-topics-topic-id)
+
+### `mail.topics.update(topicId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/topics/{topic_id}` → `Mail.Topic`
+
+Update a topic.
+
+`default_subscription` cannot change: flipping it would silently subscribe or unsubscribe everyone who never chose.
+
+- Params: `Mail.TopicUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `TOPIC_NOT_FOUND` | No such topic (`TOPIC_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `TOPIC_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Another topic has this name (`TOPIC_EXISTS`), or `IDEMPOTENCY_KEY_REUSE`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const topic = await mail.topics.update("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { description: "string" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-topics-topic-id)
+
+## webhooks
+
+### `mail.webhooks.unwrap({ payload, headers, secret? })`
+
+Verifies the signature and returns `Mail.UnwrapWebhookEvent`. Events: `contact.created`, `contact.deleted`, `contact.updated`, `domain.created`, `domain.deleted`, `domain.updated`, `domain.verified`, `email.bounced`, `email.canceled`, `email.clicked`, `email.complained`, `email.delivered`, `email.delivery_delayed`, `email.failed`, `email.opened`, `email.received`, `email.scheduled`, `email.sent`, `email.skipped`, `email.suppressed`, `sending_defaults.updated`, `suppression.added`, `suppression.removed`, plus `UnknownWebhookEvent` for types added later.
+
+## webhooks.attempts
+
+### `mail.webhooks.attempts.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/webhooks/attempts` → `PagePromise<Mail.OutboundWebhookAttempt>`
+
+Delivery attempts across all of this workspace's webhook endpoints, newest first, cursor-paginated, optionally for one event or one endpoint. Includes status code, latency, response body (truncated to 1KB), and error if any.
+
+- Params: `Mail.WebhookAttemptListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid `limit`, `cursor`, `event_id` or `endpoint_id`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const attempt of mail.webhooks.attempts.list()) {
+  console.log(attempt);
+}
+const page = await mail.webhooks.attempts.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-webhooks-attempts)
+
+## webhooks.endpoints
+
+### `mail.webhooks.endpoints.create(params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/webhooks/endpoints` → `Mail.WebhookEndpointWithSecret`
+
+Add a webhook endpoint. Returns its signing secret once.
+
+Deliveries are signed with the Standard Webhooks headers `webhook-id`, `webhook-timestamp` and `webhook-signature` (`v1,<base64 HMAC-SHA256 of "<id>.<timestamp>.<body>">`); the returned `whsec_…` secret works unchanged with any Standard Webhooks library. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h.
+
+- Params: `Mail.WebhookEndpointCreateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `WEBHOOK_EVENT_TYPE_UNKNOWN` | Validation failure: URL not https with a public host, or an unknown event type (`WEBHOOK_EVENT_TYPE_UNKNOWN`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 409 | `ConflictError` | `CONFLICT`, `WEBHOOK_ENDPOINT_LIMIT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Already 10 endpoints (`WEBHOOK_ENDPOINT_LIMIT`), or Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | The URL points at a private, loopback or internal address. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const webhookEndpointWithSecret = await mail.webhooks.endpoints.create({ url: "https://api.acme.com/webhooks" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-webhooks-endpoints)
+
+### `mail.webhooks.endpoints.delete(endpointId, options?)`
+
+`DELETE /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}` → `void`
+
+Delete a webhook endpoint.
+
+Queued retries are dropped. Its past attempts stay in the event log until the events expire.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `endpoint_id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+await mail.webhooks.endpoints.delete("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#delete-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id)
+
+### `mail.webhooks.endpoints.list(options?)`
+
+`GET /v1/workspaces/{workspace_id}/webhooks/endpoints` → `PagePromise<Mail.WebhookEndpoint>`
+
+List webhook endpoints, oldest first.
+
+At most 10, so this is always one page. Signing secrets are never returned here, only their last 4 characters.
+
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | The scope id in the path is malformed. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const endpoint of mail.webhooks.endpoints.list()) {
+  console.log(endpoint);
+}
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-webhooks-endpoints)
+
+### `mail.webhooks.endpoints.retrieve(endpointId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}` → `Mail.WebhookEndpoint`
+
+Get one webhook endpoint (without its secret).
+
+The endpoint's URL, subscription, on/off state, failure streak and the last 4 characters of its signing secret. The full secret is only returned when the endpoint is created or its secret is rotated.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `endpoint_id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const webhookEndpoint = await mail.webhooks.endpoints.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id)
+
+### `mail.webhooks.endpoints.rotateSecret(endpointId, params?, options?)`
+
+`POST /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}/rotate-secret` → `Mail.WebhookEndpointWithSecret`
+
+Rotate the signing secret. The new one is returned once.
+
+For `grace_hours` (default 24) the previous secret keeps signing too: `webhook-signature` then lists one `v1,` signature per secret, so receivers can switch over without dropping a delivery.
+
+- Params: `Mail.WebhookEndpointRotateSecretParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `grace_hours` out of range, or `endpoint_id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const webhookEndpointWithSecret = await mail.webhooks.endpoints.rotateSecret("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { grace_hours: 24 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id-rotate-secret)
+
+### `mail.webhooks.endpoints.test(endpointId, params, options?)`
+
+`POST /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}/test` → `Mail.WebhookDeliveryAttempt`
+
+Send a test event to this endpoint now and return the result.
+
+Delivers the catalogue example of `event_type`, signed like any delivery, with `"test": true` in the body. Works while the endpoint is switched off or not subscribed to that type, is logged in the event log, and is never retried or counted toward an automatic disable. Waits up to 15 s for your receiver.
+
+- Params: `Mail.WebhookEndpointTestParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Unknown `event_type`, or `endpoint_id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const webhookDeliveryAttempt = await mail.webhooks.endpoints.test("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { event_type: "email.sent" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id-test)
+
+### `mail.webhooks.endpoints.update(endpointId, params?, options?)`
+
+`PATCH /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}` → `Mail.WebhookEndpoint`
+
+Change a webhook endpoint: URL, description, events, on/off.
+
+Only the fields sent change. `enabled: true` (or a new URL) also clears an automatic disable. Switching off cancels queued retries. The secret is unchanged; rotate it with `POST …/rotate-secret`.
+
+- Params: `Mail.WebhookEndpointUpdateParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure, or `endpoint_id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | The new URL points at a private, loopback or internal address. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const webhookEndpoint = await mail.webhooks.endpoints.update("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", { description: "Production receiver" });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#patch-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id)
+
+## webhooks.eventTypes
+
+### `mail.webhooks.eventTypes.list(options?)`
+
+`GET /v1/workspaces/{workspace_id}/webhooks/event-types` → `Mail.ListWebhookEventTypes`
+
+List the events an endpoint can subscribe to.
+
+Each type with a plain description, its group and an example `data` object (what "Send test" delivers).
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | A resource id in the path is not a UUID, or the request failed validation (`BAD_REQUEST` / `VALIDATION_ERROR`). |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const listWebhookEventTypes = await mail.webhooks.eventTypes.list();
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-webhooks-event-types)
+
+## webhooks.events
+
+### `mail.webhooks.events.list(params?, options?)`
+
+`GET /v1/workspaces/{workspace_id}/webhooks/events` → `PagePromise<Mail.WebhookEvent>`
+
+List webhook events, newest first (kept for 30 days).
+
+Every event logged while at least one endpoint existed, with the latest state per endpoint and when the next retry is due.
+
+- Params: `Mail.WebhookEventListParams`
+- Paginated: `for await` iterates every item; `await` gives one page
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid filter value or cursor. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND` | Workspace not found: no workspace has this `workspaceId`, or it is not a UUID (`NOT_FOUND`). A workspace the caller is not a member of answers 403. Routes that read a resource also answer 404 when the resource is missing. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+for await (const event of mail.webhooks.events.list()) {
+  console.log(event);
+}
+const page = await mail.webhooks.events.list({}, { timeout: 5_000 });
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-webhooks-events)
+
+### `mail.webhooks.events.replay(eventId, params?, options?)`
+
+`POST /v1/workspaces/{workspace_id}/webhooks/events/{event_id}/replay` → `Mail.ReplayWebhookEvent`
+
+Send a logged event again, to its endpoints or to one endpoint.
+
+Same body and `webhook-id`, freshly signed, to every switched-on endpoint that receives this event type now, or only to `endpoint_id`. Waits for the receivers (up to 15 s each) and returns the attempts. A success cancels a retry still queued for that endpoint.
+
+- Params: `Mail.WebhookEventReplayParams`
+- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `event_id` is not `evt_<uuid>`, or `endpoint_id` is not a UUID. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_EVENT_NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such event here (`WEBHOOK_EVENT_NOT_FOUND`); events are kept for 30 days. Or No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
+| 409 | `ConflictError` | `CONFLICT`, `WEBHOOK_ENDPOINT_NOT_SUBSCRIBED`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `endpoint_id` is switched off or does not receive this event type (`WEBHOOK_ENDPOINT_NOT_SUBSCRIBED`), or Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const replayWebhookEvent = await mail.webhooks.events.replay("event");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#post-v1-workspaces-workspace-id-webhooks-events-event-id-replay)
+
+### `mail.webhooks.events.retrieve(eventId, options?)`
+
+`GET /v1/workspaces/{workspace_id}/webhooks/events/{event_id}` → `Mail.WebhookEventDetail`
+
+Get one webhook event with every delivery attempt.
+
+The event as it was sent (`type`, `data`) and every delivery attempt to every endpoint, with its trigger, HTTP status, error and the start of the response body. Use it to debug a receiver, then `replay` to send it again.
+
+| Status | Error class | Codes | When |
+|---|---|---|---|
+| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `event_id` is not `evt_<uuid>`. |
+| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token. |
+| 403 | `PermissionDeniedError` | `FORBIDDEN` | The caller lacks the action this route requires on the resource, or Mail is not enabled for the workspace. |
+| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_EVENT_NOT_FOUND` | No such event here (`WEBHOOK_EVENT_NOT_FOUND`); events are kept for 30 days. |
+| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
+
+```ts
+const webhookEventDetail = await mail.webhooks.events.retrieve("event");
+```
+
+[HTTP reference](https://productcraft.co/docs/mail/api-reference#get-v1-workspaces-workspace-id-webhooks-events-event-id)
+
+## Error codes
+
+`err.code` on an `APIError` is one of these (an open set: new codes may appear).
+
+| Code | Meaning |
+|---|---|
+| `BAD_REQUEST` | The request is malformed (not valid JSON, a bad header, an unusable parameter). |
+| `VALIDATION_ERROR` | One or more request fields are invalid; `errors` lists each field (`param`, `message`, `code`). |
+| `UNAUTHORIZED` | No credentials, or the token or API key is invalid, expired or revoked. |
+| `PAYMENT_REQUIRED` | The workspace has no credit or plan for this operation. |
+| `FORBIDDEN` | The caller is authenticated but not allowed to do this. |
+| `NOT_FOUND` | The resource does not exist, or belongs to another workspace or app. |
+| `METHOD_NOT_ALLOWED` | The route does not accept this HTTP method. |
+| `NOT_ACCEPTABLE` | The route cannot produce the requested content type. |
+| `REQUEST_TIMEOUT` | The request took too long to arrive. |
+| `CONFLICT` | The request conflicts with the current state of the resource. |
+| `GONE` | The resource existed but has been removed for good. |
+| `PRECONDITION_FAILED` | A precondition header did not match. |
+| `PAYLOAD_TOO_LARGE` | The request body is over the size limit. |
+| `UNSUPPORTED_MEDIA_TYPE` | The request body is not in a content type the route accepts. |
+| `UNPROCESSABLE_ENTITY` | The request is well-formed but cannot be carried out. |
+| `PRECONDITION_REQUIRED` | The route requires a precondition header. |
+| `RATE_LIMITED` | Too many requests; retry after the `Retry-After` header. |
+| `INTERNAL_SERVER_ERROR` | An unexpected server error. Retrying is safe for idempotent requests; quote `request_id` to support. |
+| `NOT_IMPLEMENTED` | The server does not support this operation. |
+| `BAD_GATEWAY` | An upstream service returned an invalid response. |
+| `SERVICE_UNAVAILABLE` | The service or one of its dependencies is temporarily unavailable; retry. |
+| `GATEWAY_TIMEOUT` | An upstream service did not answer in time; retry. |
+| `SERVICE_NOT_ENABLED` | The workspace has not enabled this product. |
+| `INVALID_CREDENTIALS` | The credentials were not accepted. |
+| `SESSION_REVOKED` | The session behind this token was signed out or revoked. |
+| `MCP_NOT_PERMITTED` | An MCP (agent) token cannot call this route. |
+| `MCP_WORKSPACE_MISMATCH` | The MCP token was issued for a different workspace. |
+| `PAK_NOT_PERMITTED` | A workspace API key cannot call this route. |
+| `ACTIONS_NOT_GRANTABLE` | The policy grants actions the caller does not hold. |
+| `IDEMPOTENCY_KEY_REUSE` | The `Idempotency-Key` was already used with a different body or route. |
+| `IDEMPOTENCY_KEY_REQUIRED` | This operation requires an `Idempotency-Key` header. |
+| `IDEMPOTENCY_IN_PROGRESS` | A request with the same `Idempotency-Key` is still running. Retry after `Retry-After` seconds with the same key to get its response. |
+| `WEBHOOK_ENDPOINT_LIMIT` | The workspace has the maximum number of webhook endpoints. |
+| `WEBHOOK_ENDPOINT_NOT_FOUND` | No webhook endpoint with this id in this workspace. |
+| `WEBHOOK_ENDPOINT_NOT_SUBSCRIBED` | The endpoint is not subscribed to this event type. |
+| `WEBHOOK_EVENT_NOT_FOUND` | No webhook event with this id in this workspace. |
+| `WEBHOOK_EVENT_TYPE_UNKNOWN` | The event type is not one this product sends. |
+| `AUDIENCE_REQUIRED` | Pass segment_id, topic_id, or both. |
+| `BROADCAST_AUDIENCE_EMPTY` | Nobody in this audience can receive the broadcast. |
+| `BROADCAST_CONTENT_CONFLICT` | Use a template or inline html, not both. |
+| `BROADCAST_NOT_CANCELABLE` | The broadcast cannot be canceled in its current status. |
+| `BROADCAST_NOT_DELETABLE` | The broadcast cannot be deleted in its current status; cancel it first. |
+| `BROADCAST_NOT_DRAFT` | The broadcast is no longer a draft (`details.status`). |
+| `BROADCAST_NOT_FOUND` | Broadcast not found. |
+| `BROADCAST_NOT_READY` | The broadcast cannot be sent yet (`details.problems`). |
+| `CAPABILITY_NOT_VERIFIED` | A verified domain cannot gain sending or receiving until the new records verify (`details.records`). |
+| `CONTACT_EXISTS` | A contact with this email already exists. |
+| `CONTACT_LIMIT` | The workspace has the maximum number of contacts. |
+| `CONTACT_NOT_FOUND` | Contact not found. |
+| `CONTACT_PROPERTY_EXISTS` | A contact property with this key already exists. |
+| `CONTACT_PROPERTY_LIMIT` | The workspace has the maximum number of contact properties. |
+| `CONTACT_PROPERTY_NOT_FOUND` | Contact property not found. |
+| `DATE_RANGE_BEYOND_RETENTION` | The date range reaches past the data retention window. |
+| `DATE_RANGE_TOO_WIDE` | The date range is wider than allowed. |
+| `DATE_WINDOW_TOO_WIDE` | The date window is longer than the message log retention. |
+| `DKIM_KEY_MISSING` | The domain has no DKIM key yet. |
+| `DNS_CONFLICTS` | Some records cannot be written without breaking existing ones; nothing was changed. |
+| `DOMAIN_CONNECT_DISABLED` | Domain Connect is turned off. |
+| `DOMAIN_CONNECT_MAIL_FROM_LABEL` | Domain Connect cannot apply a custom MAIL FROM label. |
+| `DOMAIN_CONNECT_NOT_SENDING` | Domain Connect needs a sending domain. |
+| `DOMAIN_CONNECT_UNAVAILABLE` | The DNS provider does not support Domain Connect for this domain. |
+| `DOMAIN_HAS_MAILBOXES` | The domain still has active mailboxes (`details.mailboxes`). |
+| `DOMAIN_NOT_FOUND` | Domain not found in this workspace. |
+| `EMAIL_CONTENT_CONFLICT` | Send either `html`/`text` or a `template`, not both, and at least one of them. |
+| `EMAIL_NOT_FOUND` | Email not found in this workspace. |
+| `EMAIL_UNAVAILABLE` | Emailing share links is temporarily unavailable. Create the link without email_to and send it yourself. |
+| `FROM_DOMAIN_MISMATCH` | The From address is not at this domain. |
+| `IDEMPOTENCY_KEY_CONFLICTS_WITH_ROW` | An `idempotency_key` on a batch row conflicts with the request key. |
+| `IMPORT_IN_PROGRESS` | Another contact import is running for this workspace. |
+| `IMPORT_NOT_FOUND` | Import not found. |
+| `IMPORT_TOO_LARGE` | The import file is over the size limit. |
+| `INVALID_CAPABILITIES` | At least one capability (sending or receiving) must be enabled. |
+| `INVALID_CONTACT_PROPERTY_VALUE` | A contact property value does not match the property type. |
+| `INVALID_CSV` | The first line must be a header with an "email" column. |
+| `INVALID_DATE` | A date is not valid ISO 8601. |
+| `INVALID_DATE_RANGE` | The date range is invalid (start after end). |
+| `INVALID_DATE_WINDOW` | The date window is invalid. |
+| `INVALID_FORMAT` | A path or query value is not in the expected format. |
+| `INVALID_FROM_ADDRESS` | The From address could not be parsed. |
+| `INVALID_SEGMENT_RULE` | The segment rule is invalid (`details.problems`). |
+| `INVALID_TIMEZONE` | The time zone is not a valid IANA name. |
+| `INVALID_ZONE` | The DNS zone is not one this domain belongs to. |
+| `MAIL_FROM_HOST_IN_USE` | The MAIL FROM host already has records that are not ours (`details.found`). |
+| `MAIL_FROM_NOT_SENDING` | A custom MAIL FROM needs the domain to send. |
+| `MAIL_HEADER_NOT_ALLOWED` | A custom header is not allowed, or its value is invalid (`details.headers`). |
+| `PROVIDER_ERROR` | The DNS provider returned an error. |
+| `PROVIDER_PERMISSION_DENIED` | The DNS provider token lacks permission to edit this zone. |
+| `PROVIDER_TOKEN_REJECTED` | The DNS provider rejected the token. |
+| `PROVIDER_UNAVAILABLE` | The DNS provider is unavailable; try again later. |
+| `PROVIDER_ZONE_NOT_FOUND` | The DNS provider has no zone for this domain. |
+| `RECIPIENT_LIMIT` | More than 50 recipients across `to`, `cc` and `bcc`. |
+| `RECIPIENT_SUPPRESSED` | The recipient is suppressed for this workspace or topic (`details.reason`). |
+| `REGION_NOT_AVAILABLE` | `region` is not the region this deployment sends from (`details.available`). |
+| `RESERVED_PROPERTY_KEY` | The property key is reserved. |
+| `SEGMENT_EXISTS` | A segment with this name already exists. |
+| `SEGMENT_LIMIT` | The workspace has the maximum number of segments. |
+| `SEGMENT_NOT_FOUND` | Segment not found. |
+| `SEGMENT_RULE_BASED` | Members of a rule segment follow its rule: change the contact or the rule instead. |
+| `SEGMENT_TYPE_FIXED` | A static segment cannot take a rule: create a rule segment instead. |
+| `SES_IDENTITY_DELETE_FAILED` | The sending identity could not be removed from the email provider; retry. |
+| `SHARE_LINK_NOT_FOUND` | This setup link does not exist, has expired or was revoked. |
+| `SMTP_AUTH_PARTIAL` | SMTP username and password must be set together. |
+| `SMTP_CONFIG_NOT_FOUND` | No SMTP override saved for this domain. |
+| `SMTP_PASSWORD_REQUIRED` | An SMTP password is required. |
+| `TEMPLATE_DATA_INVALID` | The render data does not match the template schema. |
+| `TEMPLATE_KIND_NOT_SENDABLE` | This template kind (a partial or layout) cannot be sent on its own. |
+| `TEMPLATE_NOT_FOUND` | No template with this name in this workspace. |
+| `TEMPLATE_RENDER_FAILED` | The template could not be rendered. |
+| `TLS_ENFORCED_NOT_AVAILABLE` | `tls: enforced` is not available yet. |
+| `TOPIC_EXISTS` | A topic with this name already exists. |
+| `TOPIC_LIMIT` | The workspace has the maximum number of topics. |
+| `TOPIC_NOT_FOUND` | Topic not found. |
+| `TRACKING_NOT_AVAILABLE` | Open and click tracking are not available yet. |
+| `UNKNOWN_CONTACT_PROPERTY` | The contact property is not defined; create it first. |
+| `UNSUBSCRIBE_LINK_REQUIRED` | A broadcast body must contain `{{{unsubscribe_url}}}`. |
+| `domain_not_verified_by_provider` | The From domain's DNS records have been broken for over 72 h, so it no longer sends. |
+| `from_domain_not_verified` | The From domain is not an active sending domain of this workspace (`details: { fqdn, reason }`). |
+| `no_default_sender` | No `from` and the workspace has no default sender. |
+| `sender_domain_not_in_workspace` | The address is not on a sending domain of this workspace (`details.fqdn`). |