@wspc/cli 0.0.14 → 0.0.15

package/spec/openapi.json

@@ -1162,7 +1162,7 @@
           "expected_version": {
             "type": "integer",
             "minimum": 0,
-            "description": "Optional optimistic lock. Omit to let the server use the current version; pass only to fail the call if someone else has mutated the event since you last read. On mismatch the server returns 409 `VERSION_CONFLICT` with `extra.expected_version` and `extra.actual_version`."
+            "description": "Optional optimistic lock. Omit to let the server use the current version; pass only to fail the call if someone else has mutated the event since you last read. On mismatch the server returns 409 `VERSION_CONFLICT` and includes the current and sent versions in the message."
           },
           "title": {
             "type": "string",
@@ -1371,7 +1371,8 @@
                         "identity_verification",
                         "dkim",
                         "mail_from",
-                        "receiving_mx"
+                        "receiving_mx",
+                        "dmarc"
                       ],
                       "description": "Why this DNS record is required, when the provider returns a purpose hint."
                     },
@@ -1464,15 +1465,6 @@
           "not_found"
         ]
       },
-      "GetAttachmentQuery": {
-        "type": "object",
-        "properties": {
-          "include_deleted": {
-            "type": "string",
-            "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`."
-          }
-        }
-      },
       "EmailDomainParam": {
         "type": "object",
         "properties": {
@@ -1485,6 +1477,15 @@
           "domain"
         ]
       },
+      "GetAttachmentQuery": {
+        "type": "object",
+        "properties": {
+          "include_deleted": {
+            "type": "string",
+            "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`."
+          }
+        }
+      },
       "GetEmailQuery": {
         "type": "object",
         "properties": {
@@ -1586,7 +1587,8 @@
                           "identity_verification",
                           "dkim",
                           "mail_from",
-                          "receiving_mx"
+                          "receiving_mx",
+                          "dmarc"
                         ],
                         "description": "Why this DNS record is required, when the provider returns a purpose hint."
                       },
@@ -11921,6 +11923,18 @@
           }
         },
         "summary": "Schedule a calendar event",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nCreate a new calendar event owned by the authenticated user.\n\n### When to Use\nBook a meeting, lunch, all-day trip, or any time-bound item. Optionally provide `attendees` to automatically dispatch invitation emails containing an `.ics` REQUEST attachment to each participant as a side effect.\n\n### Constraints\n- **Format Integrity**: `start` and `end` must be of the exact same type (both ISO 8601 datetimes with offset, or both ISO date-only for all-day).\n- **Chronological Order**: `end` must be strictly after `start`.\n- **All-Day boundary**: All-day events use RFC 5545 exclusive end (e.g., a one-day event on June 1st is specified as `start=2026-06-01` and `end=2026-06-02`).\n- **Attendee Limit**: Up to 50 unique attendees are supported after case-insensitive email address deduplication.\n\n### Troubleshooting\n- Returns 400 `VALIDATION_ERROR` if `start` and `end` format mismatch, or if `end <= start`.\n- Returns 400 `ATTENDEE_LIMIT_EXCEEDED` if more than 50 unique attendees are supplied.\n- Invitation emails are processed and dispatched asynchronously via Cloudflare `waitUntil`; the analytics counter `event_created` is emitted automatically.",
         "security": [
           {
@@ -11997,6 +12011,14 @@
         "responses": {
           "201": {
             "description": "The event was created. Response carries the full row including server-assigned `id`, `version: 1`, derived `all_day`, and (if applicable) `attendees`. Invitation emails are sent asynchronously via `waitUntil`.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -12399,25 +12421,17 @@
           }
         },
         "summary": "List calendar events",
-        "description": "### Overview\nReturn the authenticated user's events, ordered by `start` ascending, with cursor pagination.\n\n### When to Use\nRender calendar list/grid views, search for specific terms using full-text search, query events within a specific time window, or retrieve historically past events.\n\n### Constraints\n- **Default Visibility**: By default, soft-deleted events and past events (events where `end` is before the current time) are automatically hidden.\n- **Time Bounds Override**: Supplying any explicit time bound query parameter (`start_from`, `start_to`, `end_from`, `end_to`) or passing `include_past=true` overrides and disables the implicit past filter.\n- **Search Scope**: `q` performs a case-insensitive substring search across `title`, `description`, and `location`.\n- **Pagination**: The `limit` query parameter is clamped to `[1, 200]`; cursor pagination is enabled via the opaque `cursor` parameter.\n\n### Troubleshooting\n- Returns 400 `VALIDATION_ERROR` if date query bounds are invalid (e.g. `start_from > start_to` or `end_from > end_to`).",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -G https://api.wspc.ai/calendar/events \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"start_from=2026-06-01T00:00:00+08:00\" \\\n  --data-urlencode \"start_to=2026-06-30T23:59:59+08:00\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc event ls --from \"next Monday\" --to \"next Friday\""
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -12509,9 +12523,35 @@
             "in": "query"
           }
         ],
+        "description": "### Overview\nReturn the authenticated user's events, ordered by `start` ascending, with cursor pagination.\n\n### When to Use\nRender calendar list/grid views, search for specific terms using full-text search, query events within a specific time window, or retrieve historically past events.\n\n### Constraints\n- **Default Visibility**: By default, soft-deleted events and past events (events where `end` is before the current time) are automatically hidden.\n- **Time Bounds Override**: Supplying any explicit time bound query parameter (`start_from`, `start_to`, `end_from`, `end_to`) or passing `include_past=true` overrides and disables the implicit past filter.\n- **Search Scope**: `q` performs a case-insensitive substring search across `title`, `description`, and `location`.\n- **Pagination**: The `limit` query parameter is clamped to `[1, 200]`; cursor pagination is enabled via the opaque `cursor` parameter.\n\n### Troubleshooting\n- Returns 400 `VALIDATION_ERROR` if date query bounds are invalid (e.g. `start_from > start_to` or `end_from > end_to`).",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -G https://api.wspc.ai/calendar/events \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"start_from=2026-06-01T00:00:00+08:00\" \\\n  --data-urlencode \"start_to=2026-06-30T23:59:59+08:00\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc event ls --from \"next Monday\" --to \"next Friday\""
+          }
+        ],
         "responses": {
           "200": {
             "description": "Events matching the filters. Empty `events` array when nothing matches. `next_cursor` is present iff there is another page.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -12919,6 +12959,28 @@
           }
         },
         "summary": "Soft-delete a calendar event",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
+            },
+            "required": true,
+            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nSoft-delete an existing calendar event, hiding it from default listings.\n\n### When to Use\nRemove an event entirely from the user's historical view and calendar client. If the meeting was cancelled but should remain in history (notifying participants of cancellation), use `PATCH /calendar/events/{id}` with `status: cancelled` instead.\n\n### Constraints\n- **Optimistic Locking**: Supports optional optimistic locking via `expected_version` in the request body.\n- **Side Effects**: When soft-deleting an event with attendees, all participants will asynchronously receive a cancellation email containing an `.ics` CANCEL attachment via Cloudflare `waitUntil`.\n- **Recovery**: The record is preserved in the database as a soft-deleted row and can be brought back using `POST /calendar/events/{id}/restore`.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, or has already been soft-deleted.\n- Returns 409 `VERSION_CONFLICT` if `expected_version` does not match the database value.",
         "security": [
           {
@@ -12937,18 +12999,6 @@
             "source": "wspc event rm evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
-            },
-            "required": true,
-            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -12973,6 +13023,14 @@
         "responses": {
           "200": {
             "description": "The event was soft-deleted. Response carries `id`, `deleted_at`, and the post-delete `version`. Cancellation emails are sent asynchronously.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -13344,25 +13402,17 @@
           }
         },
         "summary": "Get a calendar event by id",
-        "description": "### Overview\nFetch a single calendar event by its unique ID, returning the complete record including all attendees.\n\n### When to Use\nDisplay a detailed view of an event, or read the latest database state (capturing `version`) prior to executing an optimistic-locked PATCH update.\n\n### Constraints\n- **Deleted Events**: Soft-deleted events return 404 `NOT_FOUND` by default. You must explicitly pass `include_deleted=true` in the query parameters to retrieve a soft-deleted row.\n- **ICS Format**: To download the RFC 5545 iCalendar text representation of this event, use `GET /calendar/events/{id}.ics` instead.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, is soft-deleted (without `include_deleted=true`), or is owned by another user.",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/calendar/events/evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc event show evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -13384,9 +13434,35 @@
             "in": "query"
           }
         ],
+        "description": "### Overview\nFetch a single calendar event by its unique ID, returning the complete record including all attendees.\n\n### When to Use\nDisplay a detailed view of an event, or read the latest database state (capturing `version`) prior to executing an optimistic-locked PATCH update.\n\n### Constraints\n- **Deleted Events**: Soft-deleted events return 404 `NOT_FOUND` by default. You must explicitly pass `include_deleted=true` in the query parameters to retrieve a soft-deleted row.\n- **ICS Format**: To download the RFC 5545 iCalendar text representation of this event, use `GET /calendar/events/{id}.ics` instead.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, is soft-deleted (without `include_deleted=true`), or is owned by another user.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/calendar/events/evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc event show evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+          }
+        ],
         "responses": {
           "200": {
             "description": "The requested event. Includes `deleted_at` only when fetched with `include_deleted=true` on a soft-deleted row.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -13794,6 +13870,28 @@
           }
         },
         "summary": "Update a calendar event",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
+            },
+            "required": true,
+            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nPartially update fields of an existing calendar event. All properties in the request body are optional.\n\n### When to Use\nReschedule an event, update its location or notes, cancel the meeting (retaining the record but notifying participants), or replace/update the attendee list.\n\n### Constraints\n- **Optimistic Locking**: Pass `expected_version` to fail with `VERSION_CONFLICT` if another mutation occurred concurrently since you last read. Omit to let the server force the update.\n- **Field Clearing**: Pass an empty string `\"\"` for `description`, `location`, or `url` to clear those fields in the database.\n- **Attendee replacement**: Providing the `attendees` property fully REPLACES the existing participant list. The server automatically diffs participants and asynchronously sends invitations (for newly added), updates (for kept), or cancellations (for removed) via Cloudflare `waitUntil`.\n- **Validation Rules**: Mismatched start/end formats or chronological order violations will fail the request.\n- **Attendee Limit**: A maximum of 50 unique attendees is allowed.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist or is soft-deleted.\n- Returns 409 `VERSION_CONFLICT` if `expected_version` is provided but stale.\n- Returns 400 `VALIDATION_ERROR` if `start` and `end` kinds do not match, or if `end <= start`.\n- Returns 400 `ATTENDEE_LIMIT_EXCEEDED` if unique attendees exceed 50.",
         "security": [
           {
@@ -13812,18 +13910,6 @@
             "source": "wspc event set evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  --start \"tomorrow 1pm\" --end \"tomorrow 2pm\""
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
-            },
-            "required": true,
-            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -13872,6 +13958,14 @@
         "responses": {
           "200": {
             "description": "The updated event with `version` incremented. Attendee diff emails are sent asynchronously.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -14250,6 +14344,28 @@
           }
         },
         "summary": "Download event as `.ics`",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "`<event_id>.ics`. The `.ics` suffix is required so the router matches this endpoint ahead of the JSON detail route."
+            },
+            "required": true,
+            "description": "`<event_id>.ics`. The `.ics` suffix is required so the router matches this endpoint ahead of the JSON detail route.",
+            "name": "filename",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nReturn a single event rendered as an RFC 5545 `.ics` file suitable for import into major calendar clients.\n\n### When to Use\nExpose a 'Save to my calendar' link in email notifications, show a download button in a UI, or programmatically forward raw iCalendar text to third parties.\n\n### Constraints\n- **Router Match**: The path parameter `filename` must be exactly `<event_id>.ics`. The `.ics` suffix is strictly required for the router to match this endpoint ahead of the JSON detail endpoint.\n- **Response Payload**: The response is plain text containing the iCalendar specification, NOT JSON. The `Content-Type` is set to `text/calendar; charset=utf-8` with `Content-Disposition: inline; filename=\"<event_id>.ics\"`.\n- **Authentication**: Standard authentication is required (Bearer API key or OAuth access token), as this endpoint is secure.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, is soft-deleted, or is owned by another user.",
         "security": [
           {
@@ -14268,21 +14384,17 @@
             "source": "wspc event ics evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F > event.ics"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "`<event_id>.ics`. The `.ics` suffix is required so the router matches this endpoint ahead of the JSON detail route."
-            },
-            "required": true,
-            "description": "`<event_id>.ics`. The `.ics` suffix is required so the router matches this endpoint ahead of the JSON detail route.",
-            "name": "filename",
-            "in": "path"
-          }
-        ],
         "responses": {
           "200": {
             "description": "RFC 5545 iCalendar payload as plain text. Content-Type `text/calendar; charset=utf-8`. Body begins with `BEGIN:VCALENDAR` and contains a single `VEVENT` for this event.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "text/calendar": {
                 "schema": {
@@ -14628,6 +14740,28 @@
           "hidden": true
         },
         "summary": "Restore a soft-deleted event",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
+            },
+            "required": true,
+            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nRestore a previously soft-deleted calendar event, making it active and visible in default list queries.\n\n### When to Use\nRecover an event that was accidentally soft-deleted.\n\n### Constraints\n- **Optimistic Locking**: Supports optional optimistic locking via `expected_version` in the request body.\n- **Side Effects**: When restoring an event with attendees, all participants will asynchronously receive a new invitation email containing an `.ics` REQUEST attachment via Cloudflare `waitUntil`.\n- **State Integrity**: You cannot restore a live (non-deleted) event. Restoring a live event is treated as an error.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, or is NOT currently soft-deleted.\n- Returns 409 `VERSION_CONFLICT` if `expected_version` does not match the database value.",
         "security": [
           {
@@ -14641,18 +14775,6 @@
             "source": "curl -X POST https://api.wspc.ai/calendar/events/evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F/restore \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
-            },
-            "required": true,
-            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -14677,6 +14799,14 @@
         "responses": {
           "200": {
             "description": "The restored event with `version` incremented and `deleted_at` cleared. Re-invitation emails are sent asynchronously to attendees.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -15043,12 +15173,24 @@
           "EmailAliases"
         ],
         "summary": "Create a receiving alias",
-        "description": "### Overview\nReserves and provisions a new passwordless/disposable receiving email alias address under the configured WSPC domain or a fully verified organization custom domain. All inbound emails received on this alias will be forwarded into the caller's inbox.\n\n### When to Use\n- Use this endpoint to spin up a fresh, dedicated email address (e.g., `alice-shop@wspc.app`) for specific websites, newsletters, or contexts to prevent spam or categorize incoming mail.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Alias Formatting**: The local part must be between 5 and 32 characters, start with an alphanumeric character, and only contain letters, numbers, dots, underscores, and hyphens.\n- **Custom Domains**: If the address uses a non-platform host, that domain must be registered to the caller's organization and have `status = verified`, `sending_status = verified`, and `receiving_status = verified`.\n- **Limit Check**: Each user is allowed a maximum of 10 active email aliases. Soft-deleted aliases do not count against this quota limit.\n\n### Troubleshooting\n- **401 Unauthorized**: Bearer token is missing, invalid, or expired.\n- **400 Bad Request / INVALID_CHARSET / RESERVED**: The alias local part contains invalid characters, is too short/long, or matches a reserved keyword.\n- **400 Bad Request / DOMAIN_NOT_FOUND**: The custom domain is not registered to the caller's organization.\n- **400 Bad Request / UNVERIFIED_DOMAIN**: The custom domain exists but is not verified yet.\n- **400 Bad Request / CUSTOM_DOMAIN_NOT_READY**: The custom domain exists but has not completed sending or receiving verification.\n- **409 Conflict / ALIAS_CONFLICT**: An alias with the exact requested email address already exists globally (whether active or soft-deleted by any user).\n- **429 Too Many Requests / ALIAS_LIMIT_EXCEEDED**: The user has reached the active alias cap limit of 10. A previously deleted alias must be cleaned up or wait for quota availability.",
+        "description": "### Overview\nReserves and provisions a new passwordless/disposable receiving email alias address under the configured WSPC domain or a fully verified organization custom domain. All inbound emails received on this alias will be forwarded into the caller's inbox.\n\n### When to Use\n- Use this endpoint to spin up a fresh, dedicated email address (e.g., `alice-shop@wspc.app`) for specific websites, newsletters, or contexts to prevent spam or categorize incoming mail.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Alias Formatting**: The local part must be between 5 and 32 characters, start with an alphanumeric character, and only contain letters, numbers, dots, underscores, and hyphens.\n- **Custom Domains**: If the address uses a non-platform host, that domain must be registered to the caller's organization and have `status = verified`, `sending_status = verified`, and `receiving_status = verified`.\n- **Limit Check**: Each user is allowed a maximum of 10 active email aliases. Soft-deleted aliases do not count against this quota limit.\n\n### Troubleshooting\n- **401 Unauthorized**: Bearer token is missing, invalid, or expired.\n- **400 Bad Request / INVALID_CHARSET / RESERVED**: The alias local part contains invalid characters, is too short/long, or matches a reserved keyword.\n- **400 Bad Request / ALIAS_DOMAIN_NOT_FOUND**: The custom domain is not registered to the caller's organization.\n- **400 Bad Request / UNVERIFIED_DOMAIN**: The custom domain exists but is not verified yet.\n- **400 Bad Request / ALIAS_DOMAIN_NOT_READY**: The custom domain exists but has not completed sending or receiving verification.\n- **409 Conflict / ALIAS_CONFLICT**: An alias with the exact requested email address already exists globally (whether active or soft-deleted by any user).\n- **429 Too Many Requests / ALIAS_LIMIT_EXCEEDED**: The user has reached the active alias cap limit of 10. A previously deleted alias must be cleaned up or wait for quota availability.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-cli": {
           "command": "alias add",
           "positional": [
@@ -15109,6 +15251,14 @@
         "responses": {
           "201": {
             "description": "Alias created. The requested address is live immediately.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -15129,7 +15279,7 @@
             }
           },
           "400": {
-            "description": "Invalid alias email address, local part, reserved local part, missing custom domain, unverified custom domain, or custom domain that is not ready for both sending and receiving.",
+            "description": "Invalid alias email address, local part, reserved local part, missing custom domain (`ALIAS_DOMAIN_NOT_FOUND`), unverified custom domain, or custom domain that is not ready for both sending and receiving (`ALIAS_DOMAIN_NOT_READY`).",
             "content": {
               "application/json": {
                 "schema": {
@@ -15334,6 +15484,28 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "When `true`, include soft-deleted aliases (with `deleted_at` set) alongside active ones. Defaults to `false`."
+            },
+            "required": false,
+            "description": "When `true`, include soft-deleted aliases (with `deleted_at` set) alongside active ones. Defaults to `false`.",
+            "name": "include_deleted",
+            "in": "query"
+          }
+        ],
         "x-cli": {
           "command": "alias ls",
           "display": {
@@ -15364,21 +15536,17 @@
             "source": "wspc email alias ls"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "When `true`, include soft-deleted aliases (with `deleted_at` set) alongside active ones. Defaults to `false`."
-            },
-            "required": false,
-            "description": "When `true`, include soft-deleted aliases (with `deleted_at` set) alongside active ones. Defaults to `false`.",
-            "name": "include_deleted",
-            "in": "query"
-          }
-        ],
         "responses": {
           "200": {
             "description": "Aliases owned by the caller, including soft-deleted entries when requested.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -15594,12 +15762,24 @@
           "EmailDomains"
         ],
         "summary": "Register a custom email domain",
-        "description": "### Overview\nRegisters a new organization-owned custom email domain with the upstream provider and caches the returned DNS verification records in D1.\n\n### When to Use\n- Use this endpoint when onboarding a new custom email domain such as `mail.example.com`.\n- The response contains the DNS records the organization must publish before the domain can be verified.\n- This route registers the domain and returns DNS records. Custom-domain aliases require `status`, `sending_status`, and `receiving_status` to all be `verified`.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Domain ownership is globally unique across the platform. Once any organization has reserved a domain, another org cannot register it.\n- This route requires custom domain provider credentials in production because it performs a live provider registration call.\n\n### Troubleshooting\n- **400 Bad Request / DOMAIN_INVALID / DOMAIN_RESERVED**: The hostname is malformed or belongs to the platform (`wspc.app`, `wspc.ai`, or their subdomains).\n- **409 Conflict / DOMAIN_CONFLICT**: The domain is already registered by some organization.\n- **502 Bad Gateway / DOMAIN_PROVIDER_ERROR**: The upstream provider request failed, timed out, or returned an unexpected shape.",
+        "description": "### Overview\nRegisters a new organization-owned custom email domain with the upstream provider and caches the returned DNS verification records in D1.\n\n### When to Use\n- Use this endpoint when onboarding a new custom email domain such as `mail.example.com`.\n- The response contains the DNS records the organization must publish before the domain can be verified.\n- This route registers the domain and returns DNS records. Custom-domain aliases require `status`, `sending_status`, and `receiving_status` to all be `verified`.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Domain ownership is globally unique across the platform. Once any organization has reserved a domain, another org cannot register it.\n- This route requires custom domain provider credentials in production because it performs a live provider registration call.\n\n### Troubleshooting\n- **400 Bad Request / DOMAIN_INVALID / DOMAIN_RESERVED**: The hostname is malformed or belongs to the platform (`wspc.app` or its subdomains).\n- **409 Conflict / DOMAIN_CONFLICT**: The domain is already registered by some organization.\n- **502 Bad Gateway / DOMAIN_PROVIDER_ERROR**: The upstream provider request failed, timed out, or returned an unexpected shape.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-cli": {
           "command": "domain add",
           "positional": [
@@ -15648,6 +15828,14 @@
         "responses": {
           "201": {
             "description": "Custom domain registered and DNS verification records returned. Custom-domain aliases require full domain readiness before use.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -15944,6 +16132,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-cli": {
           "command": "domain ls",
           "display": {
@@ -15978,6 +16178,14 @@
         "responses": {
           "200": {
             "description": "Custom domains cached for the caller organization, including ownership, sending readiness, and receiving readiness state.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -16715,70 +16923,83 @@
         }
       }
     },
-    "/email/messages/{id}/attachments/{idx}": {
-      "get": {
-        "operationId": "email_attachment_get",
+    "/email/domains/{domain}": {
+      "delete": {
+        "operationId": "email_domain_delete",
         "tags": [
-          "Emails"
+          "EmailDomains"
         ],
-        "summary": "Download an attachment by index",
-        "description": "### Overview\nStreams the raw decoded bytes of a parsed attachment belonging to an inbound email. The response body is binary data instead of JSON.\n\n### When to Use\n- Use this endpoint when a user clicks to download a file attachment (such as an invoice PDF or image) or when an automated agent needs to process a file payload.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Response Headers**: The server sets the HTTP `Content-Type` matching the attachment's parsed MIME format and provides a `Content-Disposition: attachment; filename=\"<filename>\"` header.\n- **Soft-Deleted Parents**: Downloading files from soft-deleted emails is blocked with a 404 error, unless the query parameter `include_deleted=true` is provided.\n- **Path Parameter**: The `{idx}` must be a valid 0-based integer index pointing to the attachment list metadata.\n\n### Troubleshooting\n- **401 Unauthorized**: Invalid Bearer token.\n- **404 Not Found / EMAIL_NOT_FOUND**: The specified email ID does not exist or belongs to another user.\n- **404 Not Found / ATTACHMENT_NOT_FOUND**: The index `{idx}` is out of range for the email's attachment array.",
+        "summary": "Delete a custom email domain",
+        "description": "### Overview\nDeletes one active custom email domain for the caller organization. The worker first confirms no active aliases use the domain, deletes the upstream provider resource, then soft-deletes the cached D1 row.\n\n### When to Use\n- Use this when an organization no longer wants WSPC to manage a custom email domain.\n- Delete is only allowed when no active aliases use the domain.\n- Deleted domains are hidden from active list/get/verify/delete surfaces and cannot be self-restored in this version.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- This route requires custom domain provider credentials in production because it performs a live provider delete call.\n- Provider identifiers and provider raw errors are never returned to the client.\n\n### Troubleshooting\n- **400 Bad Request / DOMAIN_INVALID / DOMAIN_RESERVED**: The path hostname is malformed or reserved.\n- **404 Not Found / DOMAIN_NOT_FOUND**: The domain does not exist, belongs to another organization, or was already deleted.\n- **409 Conflict / DOMAIN_IN_USE**: Active aliases still use this domain.\n- **502 Bad Gateway / DOMAIN_PROVIDER_ERROR**: Provider delete failed, timed out, or credentials are missing.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
         "x-cli": {
-          "command": "_handwritten",
-          "hidden": true
+          "command": "domain rm",
+          "positional": [
+            "domain"
+          ]
         },
         "x-codeSamples": [
           {
             "lang": "shell",
             "label": "curl",
-            "source": "curl https://api.wspc.ai/email/messages/eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F/attachments/0 \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -o invoice.pdf"
+            "source": "curl -X DELETE https://api.wspc.ai/email/domains/mail.example.com \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
           },
           {
             "lang": "bash",
             "label": "wspc CLI",
-            "source": "wspc email attachment eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F 0 --output invoice.pdf"
+            "source": "wspc domain rm mail.example.com"
           }
         ],
         "parameters": [
           {
             "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          },
-          {
-            "schema": {
-              "type": "string"
+              "type": "string",
+              "description": "Custom domain hostname path parameter. URL-encode if your client requires it."
             },
             "required": true,
-            "name": "idx",
+            "description": "Custom domain hostname path parameter. URL-encode if your client requires it.",
+            "name": "domain",
             "in": "path"
-          },
-          {
-            "schema": {
-              "type": "string",
-              "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`."
-            },
-            "required": false,
-            "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`.",
-            "name": "include_deleted",
-            "in": "query"
           }
         ],
         "responses": {
-          "200": {
-            "description": "Raw attachment bytes. `Content-Type` matches the attachment's parsed MIME (often `application/pdf`, `image/jpeg`, `text/calendar`, or `application/octet-stream` when unknown). `Content-Disposition: attachment; filename=\"<filename>\"`.",
+          "204": {
+            "description": "Custom domain deleted."
+          },
+          "400": {
+            "description": "Malformed or platform-reserved domain hostname.",
             "content": {
-              "application/octet-stream": {
+              "application/json": {
                 "schema": {
-                  "type": "string"
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
                 }
               }
             }
@@ -16829,7 +17050,41 @@
             }
           },
           "404": {
-            "description": "Either the parent email is unknown / soft-deleted (`EMAIL_NOT_FOUND`) or `idx` is out of range (`ATTACHMENT_NOT_FOUND`).",
+            "description": "The domain was not found for the caller organization.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Active aliases still use this domain.",
             "content": {
               "application/json": {
                 "schema": {
@@ -16955,11 +17210,43 @@
                 }
               }
             }
+          },
+          "502": {
+            "description": "The upstream provider delete failed or provider credentials are missing.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
           }
         }
-      }
-    },
-    "/email/domains/{domain}": {
+      },
       "get": {
         "operationId": "email_domain_get",
         "tags": [
@@ -17265,52 +17552,292 @@
         }
       }
     },
-    "/email/messages/{id}": {
+    "/email/messages/{id}/attachments/{idx}": {
       "get": {
-        "operationId": "email_get",
+        "operationId": "email_attachment_get",
         "tags": [
           "Emails"
         ],
-        "summary": "Get an inbound email by id",
-        "description": "### Overview\nFetches the metadata and plain-text body of a single inbound email by its unique ID. It also returns metadata for all associated attachments and optionally resolves the rendered HTML content.\n\n### When to Use\n- Use this endpoint to display the complete detail view of an email message.\n- Use it to extract attachment files or read complex HTML layouts.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **R2 HTML Read**: The HTML body is stored in Object Storage (R2). To fetch it, explicitly pass `include_html=true` (this incurs an extra R2 read charge; leave unset if only plain text is needed).\n- Returns a 404 error if the email has been soft-deleted, unless `include_deleted=true` is set.\n\n### Troubleshooting\n- **401 Unauthorized**: Missing or expired token.\n- **404 Not Found**: The specified email ID does not exist, belongs to another user, or has been soft-deleted (without `include_deleted=true`).",
+        "summary": "Download an attachment by index",
+        "description": "### Overview\nStreams the raw decoded bytes of a parsed attachment belonging to an inbound email. The response body is binary data instead of JSON.\n\n### When to Use\n- Use this endpoint when a user clicks to download a file attachment (such as an invoice PDF or image) or when an automated agent needs to process a file payload.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Response Headers**: The server sets the HTTP `Content-Type` matching the attachment's parsed MIME format and provides a `Content-Disposition: attachment; filename=\"<filename>\"` header.\n- **Soft-Deleted Parents**: Downloading files from soft-deleted emails is blocked with a 404 error, unless the query parameter `include_deleted=true` is provided.\n- **Path Parameter**: The `{idx}` must be a valid 0-based integer index pointing to the attachment list metadata.\n\n### Troubleshooting\n- **401 Unauthorized**: Invalid Bearer token.\n- **404 Not Found / EMAIL_NOT_FOUND**: The specified email ID does not exist or belongs to another user.\n- **404 Not Found / ATTACHMENT_NOT_FOUND**: The index `{idx}` is out of range for the email's attachment array.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "x-cli": {
-          "command": "email show",
-          "positional": [
-            "id"
-          ],
-          "display": {
-            "shape": "object",
-            "format": {
-              "id": "id-short",
-              "org_id": "id-short",
-              "user_id": "id-short",
-              "received_at": "relative-time",
-              "created_at": "relative-time",
-              "read_at": "relative-time",
-              "deleted_at": "relative-time",
-              "is_read": "bool-badge"
-            },
-            "dataPath": "email"
-          }
-        },
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "idx",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`."
+            },
+            "required": false,
+            "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`.",
+            "name": "include_deleted",
+            "in": "query"
+          }
+        ],
+        "x-cli": {
+          "command": "_handwritten",
+          "hidden": true
+        },
+        "x-codeSamples": [
+          {
+            "lang": "shell",
             "label": "curl",
-            "source": "curl https://api.wspc.ai/email/messages/eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "source": "curl https://api.wspc.ai/email/messages/eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F/attachments/0 \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -o invoice.pdf"
           },
           {
             "lang": "bash",
             "label": "wspc CLI",
-            "source": "wspc email show eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+            "source": "wspc email attachment eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F 0 --output invoice.pdf"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Raw attachment bytes. `Content-Type` matches the attachment's parsed MIME (often `application/pdf`, `image/jpeg`, `text/calendar`, or `application/octet-stream` when unknown). `Content-Disposition: attachment; filename=\"<filename>\"`.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/octet-stream": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication is required but missing or invalid. The Bearer token (API key or OAuth access token) was absent, malformed, or rejected.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                },
+                "examples": {
+                  "authRequired": {
+                    "summary": "Missing Authorization header",
+                    "value": {
+                      "error": {
+                        "code": "AUTH_REQUIRED",
+                        "message": "missing bearer token"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Either the parent email is unknown / soft-deleted (`EMAIL_NOT_FOUND`) or `idx` is out of range (`ATTACHMENT_NOT_FOUND`).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limit exceeded. Retry after the duration in `error.extra.retry_after_seconds`. `limit_kind` identifies which bucket was exhausted.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                },
+                "examples": {
+                  "rateLimited": {
+                    "summary": "Per-key rate limit hit",
+                    "value": {
+                      "error": {
+                        "code": "RATE_LIMITED",
+                        "message": "rate limit exceeded",
+                        "extra": {
+                          "retry_after_seconds": 60,
+                          "limit_kind": "authenticated_per_key"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unhandled server error. The request was well-formed but the service failed unexpectedly. Safe to retry idempotent operations.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                },
+                "examples": {
+                  "internalError": {
+                    "summary": "Unhandled exception",
+                    "value": {
+                      "error": {
+                        "code": "INTERNAL_ERROR",
+                        "message": "internal error"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/email/messages/{id}": {
+      "get": {
+        "operationId": "email_get",
+        "tags": [
+          "Emails"
+        ],
+        "summary": "Get an inbound email by id",
+        "description": "### Overview\nFetches the metadata and plain-text body of a single inbound email by its unique ID. It also returns metadata for all associated attachments and optionally resolves the rendered HTML content.\n\n### When to Use\n- Use this endpoint to display the complete detail view of an email message.\n- Use it to extract attachment files or read complex HTML layouts.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **R2 HTML Read**: The HTML body is stored in Object Storage (R2). To fetch it, explicitly pass `include_html=true` (this incurs an extra R2 read charge; leave unset if only plain text is needed).\n- Returns a 404 error if the email has been soft-deleted, unless `include_deleted=true` is set.\n\n### Troubleshooting\n- **401 Unauthorized**: Missing or expired token.\n- **404 Not Found**: The specified email ID does not exist, belongs to another user, or has been soft-deleted (without `include_deleted=true`).",
+        "security": [
+          {
+            "bearerAuth": []
           }
         ],
         "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
           {
             "schema": {
               "type": "string"
@@ -17340,9 +17867,49 @@
             "in": "query"
           }
         ],
+        "x-cli": {
+          "command": "email show",
+          "positional": [
+            "id"
+          ],
+          "display": {
+            "shape": "object",
+            "format": {
+              "id": "id-short",
+              "org_id": "id-short",
+              "user_id": "id-short",
+              "received_at": "relative-time",
+              "created_at": "relative-time",
+              "read_at": "relative-time",
+              "deleted_at": "relative-time",
+              "is_read": "bool-badge"
+            },
+            "dataPath": "email"
+          }
+        },
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/email/messages/eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc email show eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+          }
+        ],
         "responses": {
           "200": {
             "description": "The email row, attachment metadata, and (when requested) the HTML body.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -17790,40 +18357,17 @@
             "bearerAuth": []
           }
         ],
-        "x-cli": {
-          "command": "email ls",
-          "display": {
-            "shape": "list",
-            "columns": [
-              "id",
-              "from_addr",
-              "subject",
-              "is_read",
-              "received_at"
-            ],
-            "format": {
-              "id": "id-short",
-              "from_addr": "truncate",
-              "subject": "truncate",
-              "is_read": "bool-badge",
-              "received_at": "relative-time"
-            },
-            "emptyMessage": "no emails"
-          }
-        },
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -G https://api.wspc.ai/email/messages \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"limit=20\" --data-urlencode \"unread_only=true\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc email ls --unread --limit 20"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -17886,9 +18430,50 @@
             "in": "query"
           }
         ],
+        "x-cli": {
+          "command": "email ls",
+          "display": {
+            "shape": "list",
+            "columns": [
+              "id",
+              "from_addr",
+              "subject",
+              "is_read",
+              "received_at"
+            ],
+            "format": {
+              "id": "id-short",
+              "from_addr": "truncate",
+              "subject": "truncate",
+              "is_read": "bool-badge",
+              "received_at": "relative-time"
+            },
+            "emptyMessage": "no emails"
+          }
+        },
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -G https://api.wspc.ai/email/messages \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"limit=20\" --data-urlencode \"unread_only=true\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc email ls --unread --limit 20"
+          }
+        ],
         "responses": {
           "200": {
             "description": "A page of inbound emails. `next_cursor` is present iff there is another page; pass it back as `cursor` to continue.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -19270,6 +19855,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-cli": {
           "command": "_handwritten",
           "hidden": true
@@ -19335,6 +19932,14 @@
         "responses": {
           "200": {
             "description": "The send was accepted. Response `email.id` uses `out_<ULID>` for new outbound rows; legacy UUID ids remain accepted. Inspect `idempotent_replay`: `false` means the provider was invoked on this request, `true` means an earlier identical send was replayed.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {