@wspc/cli 0.0.10 → 0.0.11

package/spec/openapi.json

@@ -1282,6 +1282,151 @@
           "created_at"
         ]
       },
+      "CreateDomainBody": {
+        "type": "object",
+        "properties": {
+          "domain": {
+            "type": "string",
+            "description": "Custom domain hostname to register with the provider, for example `mail.example.com`."
+          }
+        },
+        "required": [
+          "domain"
+        ]
+      },
+      "EmailDomainObjectResponse": {
+        "type": "object",
+        "properties": {
+          "domain": {
+            "type": "object",
+            "properties": {
+              "domain": {
+                "type": "string",
+                "description": "Normalized lowercase ASCII hostname for the registered custom domain."
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "pending",
+                  "verified",
+                  "failed",
+                  "temporary_failure"
+                ],
+                "description": "Overall upstream provider status for DNS ownership verification."
+              },
+              "sending_status": {
+                "type": "string",
+                "enum": [
+                  "pending",
+                  "verified",
+                  "failed",
+                  "disabled"
+                ],
+                "description": "Provider-side sending readiness signal for this domain registration. Custom-domain aliases can send only when this value is `verified`."
+              },
+              "receiving_status": {
+                "type": "string",
+                "enum": [
+                  "pending",
+                  "verified",
+                  "failed",
+                  "disabled"
+                ],
+                "description": "Provider-side receiving readiness signal for this domain registration. Custom-domain aliases can be created only when this value is `verified`."
+              },
+              "records": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "enum": [
+                        "TXT",
+                        "CNAME",
+                        "MX"
+                      ],
+                      "description": "DNS record type required by the upstream domain provider."
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "DNS hostname to create or update."
+                    },
+                    "value": {
+                      "type": "string",
+                      "description": "Expected DNS record value."
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "pending",
+                        "verified",
+                        "failed"
+                      ],
+                      "description": "Latest provider verification status for this individual DNS record."
+                    },
+                    "purpose": {
+                      "type": "string",
+                      "enum": [
+                        "identity_verification",
+                        "dkim",
+                        "mail_from",
+                        "receiving_mx"
+                      ],
+                      "description": "Why this DNS record is required, when the provider returns a purpose hint."
+                    },
+                    "ttl": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "description": "Requested TTL in seconds, if the provider specifies one."
+                    },
+                    "priority": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "description": "MX priority, when applicable."
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "name",
+                    "value",
+                    "status"
+                  ]
+                },
+                "description": "DNS records currently cached from the provider for ownership verification."
+              },
+              "region": {
+                "type": "string",
+                "description": "Provider region hint, when returned by the upstream provider."
+              },
+              "created_at": {
+                "type": "number",
+                "description": "Unix epoch milliseconds when the local cache row was created."
+              },
+              "updated_at": {
+                "type": "number",
+                "description": "Unix epoch milliseconds when the local cache row was last refreshed."
+              },
+              "verified_at": {
+                "type": "number",
+                "description": "Unix epoch milliseconds when the domain last reached overall `verified` status. Omitted until the first successful verification."
+              }
+            },
+            "required": [
+              "domain",
+              "status",
+              "sending_status",
+              "receiving_status",
+              "records",
+              "created_at",
+              "updated_at"
+            ]
+          }
+        },
+        "required": [
+          "domain"
+        ]
+      },
       "BatchIdsBody": {
         "type": "object",
         "properties": {
@@ -1328,6 +1473,18 @@
           }
         }
       },
+      "EmailDomainParam": {
+        "type": "object",
+        "properties": {
+          "domain": {
+            "type": "string",
+            "description": "Custom domain hostname path parameter. URL-encode if your client requires it."
+          }
+        },
+        "required": [
+          "domain"
+        ]
+      },
       "GetEmailQuery": {
         "type": "object",
         "properties": {
@@ -1350,6 +1507,142 @@
           }
         }
       },
+      "EmailDomainListResponse": {
+        "type": "object",
+        "properties": {
+          "domains": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "domain": {
+                  "type": "string",
+                  "description": "Normalized lowercase ASCII hostname for the registered custom domain."
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "pending",
+                    "verified",
+                    "failed",
+                    "temporary_failure"
+                  ],
+                  "description": "Overall upstream provider status for DNS ownership verification."
+                },
+                "sending_status": {
+                  "type": "string",
+                  "enum": [
+                    "pending",
+                    "verified",
+                    "failed",
+                    "disabled"
+                  ],
+                  "description": "Provider-side sending readiness signal for this domain registration. Custom-domain aliases can send only when this value is `verified`."
+                },
+                "receiving_status": {
+                  "type": "string",
+                  "enum": [
+                    "pending",
+                    "verified",
+                    "failed",
+                    "disabled"
+                  ],
+                  "description": "Provider-side receiving readiness signal for this domain registration. Custom-domain aliases can be created only when this value is `verified`."
+                },
+                "records": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "enum": [
+                          "TXT",
+                          "CNAME",
+                          "MX"
+                        ],
+                        "description": "DNS record type required by the upstream domain provider."
+                      },
+                      "name": {
+                        "type": "string",
+                        "description": "DNS hostname to create or update."
+                      },
+                      "value": {
+                        "type": "string",
+                        "description": "Expected DNS record value."
+                      },
+                      "status": {
+                        "type": "string",
+                        "enum": [
+                          "pending",
+                          "verified",
+                          "failed"
+                        ],
+                        "description": "Latest provider verification status for this individual DNS record."
+                      },
+                      "purpose": {
+                        "type": "string",
+                        "enum": [
+                          "identity_verification",
+                          "dkim",
+                          "mail_from",
+                          "receiving_mx"
+                        ],
+                        "description": "Why this DNS record is required, when the provider returns a purpose hint."
+                      },
+                      "ttl": {
+                        "type": "integer",
+                        "exclusiveMinimum": 0,
+                        "description": "Requested TTL in seconds, if the provider specifies one."
+                      },
+                      "priority": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "description": "MX priority, when applicable."
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "name",
+                      "value",
+                      "status"
+                    ]
+                  },
+                  "description": "DNS records currently cached from the provider for ownership verification."
+                },
+                "region": {
+                  "type": "string",
+                  "description": "Provider region hint, when returned by the upstream provider."
+                },
+                "created_at": {
+                  "type": "number",
+                  "description": "Unix epoch milliseconds when the local cache row was created."
+                },
+                "updated_at": {
+                  "type": "number",
+                  "description": "Unix epoch milliseconds when the local cache row was last refreshed."
+                },
+                "verified_at": {
+                  "type": "number",
+                  "description": "Unix epoch milliseconds when the domain last reached overall `verified` status. Omitted until the first successful verification."
+                }
+              },
+              "required": [
+                "domain",
+                "status",
+                "sending_status",
+                "receiving_status",
+                "records",
+                "created_at",
+                "updated_at"
+              ]
+            }
+          }
+        },
+        "required": [
+          "domains"
+        ]
+      },
       "ListEmailsQuery": {
         "type": "object",
         "properties": {
@@ -15287,61 +15580,141 @@
         }
       }
     },
-    "/email/aliases/{email}": {
-      "delete": {
-        "operationId": "email_alias_delete",
+    "/email/domains": {
+      "post": {
+        "operationId": "email_domain_create",
         "tags": [
-          "EmailAliases"
+          "EmailDomains"
         ],
-        "summary": "Soft-delete an alias",
-        "description": "### Overview\nSoft-deletes a specific active email receiving alias owned by the caller. Once soft-deleted, the alias stops accepting and forwarding any new inbound emails.\n\n### When to Use\n- Use this endpoint when decommissioning a disposable alias address that is no longer needed or is receiving excessive spam.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Data Retention**: Soft-deletion is immediate. Inbound mail forwarding stops, but historical emails previously received on this alias remain fully readable in the inbox.\n- **Restoration**: The alias remains globally reserved and cannot be created fresh by anyone; use `POST /email/aliases/{email}/restore` to reactivate.\n- **Path Parameter**: The `@` character in the `{email}` path parameter must be URL-encoded as `%40`.\n\n### Troubleshooting\n- **401 Unauthorized**: Missing or invalid token.\n- **404 Not Found**: No active alias with this exact address was found for the authenticated user, or the alias is already deleted.",
+        "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.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
         "x-cli": {
-          "command": "alias rm",
+          "command": "domain add",
           "positional": [
-            "email"
+            "domain"
           ],
           "display": {
             "shape": "object",
             "format": {
-              "id": "id-short",
-              "user_id": "id-short",
               "created_at": "relative-time",
-              "deleted_at": "relative-time"
-            }
+              "updated_at": "relative-time",
+              "verified_at": "relative-time"
+            },
+            "dataPath": "domain"
           }
         },
         "x-codeSamples": [
           {
             "lang": "shell",
             "label": "curl",
-            "source": "curl -X DELETE https://api.wspc.ai/email/aliases/alice-shop%40wspc.app \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "source": "curl -X POST https://api.wspc.ai/email/domains \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain\":\"mail.example.com\"}'"
           },
           {
             "lang": "bash",
             "label": "wspc CLI",
-            "source": "wspc email alias rm alice-shop@wspc.app"
+            "source": "wspc email domain add mail.example.com"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Full alias email address. URL-encode @ as %40 in paths."
-            },
-            "required": true,
-            "description": "Full alias email address. URL-encode @ as %40 in paths.",
-            "name": "email",
-            "in": "path"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateDomainBody"
+              },
+              "examples": {
+                "minimal": {
+                  "summary": "Register one custom domain",
+                  "value": {
+                    "domain": "mail.example.com"
+                  }
+                }
+              }
+            }
           }
-        ],
+        },
         "responses": {
-          "204": {
-            "description": "Alias soft-deleted. Forwarding stops immediately. No response body."
+          "201": {
+            "description": "Custom domain registered and DNS verification records returned. Custom-domain aliases require full domain readiness before use.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EmailDomainObjectResponse"
+                },
+                "examples": {
+                  "happyPath": {
+                    "summary": "Pending verification with DNS instructions",
+                    "value": {
+                      "domain": {
+                        "domain": "mail.example.com",
+                        "status": "pending",
+                        "sending_status": "pending",
+                        "receiving_status": "pending",
+                        "records": [
+                          {
+                            "type": "TXT",
+                            "name": "mail.example.com",
+                            "value": "pm-domain-verification=abc123",
+                            "status": "pending",
+                            "ttl": 3600,
+                            "purpose": "identity_verification"
+                          },
+                          {
+                            "type": "CNAME",
+                            "name": "selector1._domainkey.mail.example.com",
+                            "value": "selector1.domainkey.example.net",
+                            "status": "pending",
+                            "purpose": "dkim"
+                          }
+                        ],
+                        "region": "us-east-1",
+                        "created_at": 1780166400000,
+                        "updated_at": 1780166400000
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Malformed or platform-reserved domain hostname.",
+            "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"
+                  ]
+                }
+              }
+            }
           },
           "401": {
             "description": "Authentication is required but missing or invalid. The Bearer token (API key or OAuth access token) was absent, malformed, or rejected.",
@@ -15388,8 +15761,8 @@
               }
             }
           },
-          "404": {
-            "description": "No active alias with this email address is owned by the caller.",
+          "409": {
+            "description": "This domain is already registered by an organization.",
             "content": {
               "application/json": {
                 "schema": {
@@ -15515,112 +15888,9 @@
                 }
               }
             }
-          }
-        }
-      }
-    },
-    "/email/messages/delete": {
-      "post": {
-        "operationId": "email_delete",
-        "tags": [
-          "Emails"
-        ],
-        "summary": "Soft-delete inbound emails",
-        "description": "### Overview\nSoft-deletes a batch of inbound emails, moving them to the trash. Soft-deleted emails are immediately excluded from default inbox lists.\n\n### When to Use\n- Use this endpoint to trash one or more email messages from a user's inbox view.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Accepts 1 to 100 email IDs per call.\n- Deletion is fully reversible: soft-deleted rows persist in the database and can be undeleted using the restore endpoint.\n- **Data Cleanup**: Out-of-band background processes eventually purge associated raw MIME source payloads and attachment bytes from R2; deletion does not immediately free storage.\n\n### Troubleshooting\n- **401 Unauthorized**: Invalid Bearer token.\n- **400 Bad Request**: The request body is malformed or exceeds the maximum limit of 100 IDs.",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "x-cli": {
-          "command": "email rm",
-          "positional": [
-            "id"
-          ],
-          "options": {
-            "id": {
-              "array": true,
-              "mapsTo": "ids"
-            }
-          },
-          "display": {
-            "shape": "object",
-            "format": {}
-          }
-        },
-        "x-codeSamples": [
-          {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X POST https://api.wspc.ai/email/messages/delete \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ids\":[\"eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F\",\"eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3G\"]}'"
-          },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc email rm eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3G"
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/BatchIdsBody"
-              },
-              "examples": {
-                "minimal": {
-                  "summary": "Single id",
-                  "value": {
-                    "ids": [
-                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
-                    ]
-                  }
-                },
-                "full": {
-                  "summary": "Multiple ids (up to 100 per call)",
-                  "value": {
-                    "ids": [
-                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3G",
-                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3H"
-                    ]
-                  }
-                }
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "Bulk soft-delete result. `deleted` counts state changes only.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/DeleteBatchResponse"
-                },
-                "examples": {
-                  "happyPath": {
-                    "summary": "All ids matched and changed state",
-                    "value": {
-                      "deleted": 2,
-                      "not_found": []
-                    }
-                  },
-                  "partial": {
-                    "summary": "Some ids unknown to this user",
-                    "value": {
-                      "deleted": 1,
-                      "not_found": [
-                        "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3X"
-                      ]
-                    }
-                  }
-                }
-              }
-            }
           },
-          "400": {
-            "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
+          "502": {
+            "description": "The upstream provider call failed or provider credentials are missing.",
             "content": {
               "application/json": {
                 "schema": {
@@ -15649,15 +15919,128 @@
                   "required": [
                     "error"
                   ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "email_domain_list",
+        "tags": [
+          "EmailDomains"
+        ],
+        "summary": "List cached custom domains",
+        "description": "### Overview\nReturns the caller organization's cached custom email domains from D1. This route does not call the upstream provider.\n\n### When to Use\n- Use this to render an admin view of all registered domains and their latest known verification state.\n- Use it to inspect DNS records that were previously fetched during create or verify operations.\n- The cached state includes DNS ownership, sending readiness, and receiving readiness used by custom-domain alias creation.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Results are scoped to the caller organization and sorted newest-first by creation time.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "x-cli": {
+          "command": "domain ls",
+          "display": {
+            "shape": "list",
+            "columns": [
+              "domain",
+              "status",
+              "sending_status",
+              "receiving_status",
+              "updated_at"
+            ],
+            "format": {
+              "updated_at": "relative-time",
+              "verified_at": "relative-time"
+            },
+            "emptyMessage": "no domains",
+            "dataPath": "domains"
+          }
+        },
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/email/domains \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc email domain ls"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Custom domains cached for the caller organization, including ownership, sending readiness, and receiving readiness state.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EmailDomainListResponse"
                 },
                 "examples": {
-                  "validationError": {
-                    "summary": "Body failed schema validation",
+                  "happyPath": {
+                    "summary": "Two cached domains",
                     "value": {
-                      "error": {
-                        "code": "VALIDATION_ERROR",
-                        "message": "title must not be empty"
-                      }
+                      "domains": [
+                        {
+                          "domain": "mail.example.com",
+                          "status": "pending",
+                          "sending_status": "pending",
+                          "receiving_status": "pending",
+                          "records": [
+                            {
+                              "type": "TXT",
+                              "name": "mail.example.com",
+                              "value": "pm-domain-verification=abc123",
+                              "status": "pending",
+                              "ttl": 3600,
+                              "purpose": "identity_verification"
+                            },
+                            {
+                              "type": "CNAME",
+                              "name": "selector1._domainkey.mail.example.com",
+                              "value": "selector1.domainkey.example.net",
+                              "status": "pending",
+                              "purpose": "dkim"
+                            }
+                          ],
+                          "region": "us-east-1",
+                          "created_at": 1780166400000,
+                          "updated_at": 1780166400000
+                        },
+                        {
+                          "domain": "reply.example.com",
+                          "status": "verified",
+                          "sending_status": "verified",
+                          "receiving_status": "disabled",
+                          "records": [
+                            {
+                              "type": "TXT",
+                              "name": "mail.example.com",
+                              "value": "pm-domain-verification=abc123",
+                              "status": "verified",
+                              "ttl": 3600,
+                              "purpose": "identity_verification"
+                            },
+                            {
+                              "type": "CNAME",
+                              "name": "selector1._domainkey.mail.example.com",
+                              "value": "selector1.domainkey.example.net",
+                              "status": "verified",
+                              "purpose": "dkim"
+                            }
+                          ],
+                          "region": "us-east-1",
+                          "created_at": 1780166400000,
+                          "updated_at": 1780167000000,
+                          "verified_at": 1780167000000
+                        }
+                      ]
+                    }
+                  },
+                  "empty": {
+                    "summary": "No custom domains yet",
+                    "value": {
+                      "domains": []
                     }
                   }
                 }
@@ -15806,73 +16189,61 @@
         }
       }
     },
-    "/email/messages/{id}/attachments/{idx}": {
-      "get": {
-        "operationId": "email_attachment_get",
+    "/email/aliases/{email}": {
+      "delete": {
+        "operationId": "email_alias_delete",
         "tags": [
-          "Emails"
+          "EmailAliases"
         ],
-        "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": "Soft-delete an alias",
+        "description": "### Overview\nSoft-deletes a specific active email receiving alias owned by the caller. Once soft-deleted, the alias stops accepting and forwarding any new inbound emails.\n\n### When to Use\n- Use this endpoint when decommissioning a disposable alias address that is no longer needed or is receiving excessive spam.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Data Retention**: Soft-deletion is immediate. Inbound mail forwarding stops, but historical emails previously received on this alias remain fully readable in the inbox.\n- **Restoration**: The alias remains globally reserved and cannot be created fresh by anyone; use `POST /email/aliases/{email}/restore` to reactivate.\n- **Path Parameter**: The `@` character in the `{email}` path parameter must be URL-encoded as `%40`.\n\n### Troubleshooting\n- **401 Unauthorized**: Missing or invalid token.\n- **404 Not Found**: No active alias with this exact address was found for the authenticated user, or the alias is already deleted.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
         "x-cli": {
-          "command": "_handwritten",
-          "hidden": true
+          "command": "alias rm",
+          "positional": [
+            "email"
+          ],
+          "display": {
+            "shape": "object",
+            "format": {
+              "id": "id-short",
+              "user_id": "id-short",
+              "created_at": "relative-time",
+              "deleted_at": "relative-time"
+            }
+          }
         },
         "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/aliases/alice-shop%40wspc.app \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
           },
           {
             "lang": "bash",
             "label": "wspc CLI",
-            "source": "wspc email attachment eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F 0 --output invoice.pdf"
+            "source": "wspc email alias rm alice-shop@wspc.app"
           }
         ],
         "parameters": [
           {
             "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          },
-          {
-            "schema": {
-              "type": "string"
+              "type": "string",
+              "description": "Full alias email address. URL-encode @ as %40 in paths."
             },
             "required": true,
-            "name": "idx",
+            "description": "Full alias email address. URL-encode @ as %40 in paths.",
+            "name": "email",
             "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>\"`.",
-            "content": {
-              "application/octet-stream": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            }
+          "204": {
+            "description": "Alias soft-deleted. Forwarding stops immediately. No response body."
           },
           "401": {
             "description": "Authentication is required but missing or invalid. The Bearer token (API key or OAuth access token) was absent, malformed, or rejected.",
@@ -15920,7 +16291,7 @@
             }
           },
           "404": {
-            "description": "Either the parent email is unknown / soft-deleted (`EMAIL_NOT_FOUND`) or `idx` is out of range (`ATTACHMENT_NOT_FOUND`).",
+            "description": "No active alias with this email address is owned by the caller.",
             "content": {
               "application/json": {
                 "schema": {
@@ -16050,55 +16421,892 @@
         }
       }
     },
-    "/email/messages/{id}": {
-      "get": {
-        "operationId": "email_get",
+    "/email/messages/delete": {
+      "post": {
+        "operationId": "email_delete",
         "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": "Soft-delete inbound emails",
+        "description": "### Overview\nSoft-deletes a batch of inbound emails, moving them to the trash. Soft-deleted emails are immediately excluded from default inbox lists.\n\n### When to Use\n- Use this endpoint to trash one or more email messages from a user's inbox view.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Accepts 1 to 100 email IDs per call.\n- Deletion is fully reversible: soft-deleted rows persist in the database and can be undeleted using the restore endpoint.\n- **Data Cleanup**: Out-of-band background processes eventually purge associated raw MIME source payloads and attachment bytes from R2; deletion does not immediately free storage.\n\n### Troubleshooting\n- **401 Unauthorized**: Invalid Bearer token.\n- **400 Bad Request**: The request body is malformed or exceeds the maximum limit of 100 IDs.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
         "x-cli": {
-          "command": "email show",
+          "command": "email rm",
           "positional": [
             "id"
           ],
+          "options": {
+            "id": {
+              "array": true,
+              "mapsTo": "ids"
+            }
+          },
           "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"
+            "format": {}
           }
         },
         "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 -X POST https://api.wspc.ai/email/messages/delete \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ids\":[\"eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F\",\"eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3G\"]}'"
           },
           {
             "lang": "bash",
             "label": "wspc CLI",
-            "source": "wspc email show eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+            "source": "wspc email rm eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3G"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BatchIdsBody"
+              },
+              "examples": {
+                "minimal": {
+                  "summary": "Single id",
+                  "value": {
+                    "ids": [
+                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+                    ]
+                  }
+                },
+                "full": {
+                  "summary": "Multiple ids (up to 100 per call)",
+                  "value": {
+                    "ids": [
+                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3G",
+                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3H"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Bulk soft-delete result. `deleted` counts state changes only.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeleteBatchResponse"
+                },
+                "examples": {
+                  "happyPath": {
+                    "summary": "All ids matched and changed state",
+                    "value": {
+                      "deleted": 2,
+                      "not_found": []
+                    }
+                  },
+                  "partial": {
+                    "summary": "Some ids unknown to this user",
+                    "value": {
+                      "deleted": 1,
+                      "not_found": [
+                        "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3X"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
+            "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": {
+                  "validationError": {
+                    "summary": "Body failed schema validation",
+                    "value": {
+                      "error": {
+                        "code": "VALIDATION_ERROR",
+                        "message": "title must not be empty"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "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"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "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}/attachments/{idx}": {
+      "get": {
+        "operationId": "email_attachment_get",
+        "tags": [
+          "Emails"
+        ],
+        "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": "_handwritten",
+          "hidden": true
+        },
+        "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"
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc email attachment eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F 0 --output invoice.pdf"
+          }
+        ],
+        "parameters": [
+          {
+            "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"
+          }
+        ],
+        "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>\"`.",
+            "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/domains/{domain}": {
+      "get": {
+        "operationId": "email_domain_get",
+        "tags": [
+          "EmailDomains"
+        ],
+        "summary": "Get one cached custom domain",
+        "description": "### Overview\nReturns the caller organization's cached state for one custom email domain. This is a pure D1 read and never calls the upstream provider.\n\n### When to Use\n- Use this to inspect the latest cached DNS records or verification status for a single domain.\n- This cached view includes ownership, sending readiness, and receiving readiness state for custom-domain alias decisions.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- The `{domain}` path parameter is normalized and validated server-side before lookup.\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 or belongs to another organization.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "x-cli": {
+          "command": "domain show",
+          "positional": [
+            "domain"
+          ],
+          "display": {
+            "shape": "object",
+            "format": {
+              "created_at": "relative-time",
+              "updated_at": "relative-time",
+              "verified_at": "relative-time"
+            },
+            "dataPath": "domain"
+          }
+        },
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/email/domains/mail.example.com \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc email domain show mail.example.com"
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Custom domain hostname path parameter. URL-encode if your client requires it."
+            },
+            "required": true,
+            "description": "Custom domain hostname path parameter. URL-encode if your client requires it.",
+            "name": "domain",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "One custom domain cached for the caller organization, including ownership, sending readiness, and receiving readiness state.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EmailDomainObjectResponse"
+                },
+                "examples": {
+                  "happyPath": {
+                    "summary": "Pending domain cache row",
+                    "value": {
+                      "domain": {
+                        "domain": "mail.example.com",
+                        "status": "pending",
+                        "sending_status": "pending",
+                        "receiving_status": "pending",
+                        "records": [
+                          {
+                            "type": "TXT",
+                            "name": "mail.example.com",
+                            "value": "pm-domain-verification=abc123",
+                            "status": "pending",
+                            "ttl": 3600,
+                            "purpose": "identity_verification"
+                          },
+                          {
+                            "type": "CNAME",
+                            "name": "selector1._domainkey.mail.example.com",
+                            "value": "selector1.domainkey.example.net",
+                            "status": "pending",
+                            "purpose": "dkim"
+                          }
+                        ],
+                        "region": "us-east-1",
+                        "created_at": 1780166400000,
+                        "updated_at": 1780166400000
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Malformed or platform-reserved domain hostname.",
+            "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"
+                  ]
+                }
+              }
+            }
+          },
+          "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": "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"
+                  ]
+                }
+              }
+            }
+          },
+          "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": []
+          }
+        ],
+        "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"
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
             },
             "required": true,
             "name": "id",
@@ -17682,16 +18890,271 @@
                         "message"
                       ]
                     }
-                  },
-                  "required": [
-                    "error"
-                  ]
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Either restoring would exceed the per-user active-alias limit (`ALIAS_LIMIT_EXCEEDED`) or the write rate limit was hit (`RATE_LIMITED`).",
+            "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"
+                  ]
+                }
+              }
+            }
+          },
+          "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/restore": {
+      "post": {
+        "operationId": "email_restore",
+        "tags": [
+          "Emails"
+        ],
+        "summary": "Restore soft-deleted inbound emails",
+        "description": "### Overview\nRestores a batch of soft-deleted inbound emails from the trash, making them reappear in standard inbox lists.\n\n### When to Use\n- Use this endpoint to recover email messages that were trashed by mistake.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Accepts 1 to 100 email IDs. Already-active IDs are silently ignored.\n\n### Troubleshooting\n- **401 Unauthorized**: Invalid token.\n- **400 Bad Request**: Malformed request or batch limit exceeded.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "x-cli": {
+          "command": "_internal",
+          "hidden": true
+        },
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X POST https://api.wspc.ai/email/messages/restore \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ids\":[\"eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F\"]}'"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BatchIdsBody"
+              },
+              "examples": {
+                "minimal": {
+                  "summary": "Single id",
+                  "value": {
+                    "ids": [
+                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+                    ]
+                  }
+                },
+                "full": {
+                  "summary": "Multiple ids (up to 100 per call)",
+                  "value": {
+                    "ids": [
+                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3G",
+                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3H"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Bulk restore result. `restored` counts state changes only.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RestoreBatchResponse"
+                },
+                "examples": {
+                  "happyPath": {
+                    "summary": "All ids matched and changed state",
+                    "value": {
+                      "restored": 2,
+                      "not_found": []
+                    }
+                  },
+                  "partial": {
+                    "summary": "Some ids unknown to this user",
+                    "value": {
+                      "restored": 1,
+                      "not_found": [
+                        "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3X"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
+            "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": {
+                  "validationError": {
+                    "summary": "Body failed schema validation",
+                    "value": {
+                      "error": {
+                        "code": "VALIDATION_ERROR",
+                        "message": "title must not be empty"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "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"
+                      }
+                    }
+                  }
                 }
               }
             }
           },
           "429": {
-            "description": "Either restoring would exceed the per-user active-alias limit (`ALIAS_LIMIT_EXCEEDED`) or the write rate limit was hit (`RATE_LIMITED`).",
+            "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": {
@@ -17720,6 +19183,21 @@
                   "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"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -17772,28 +19250,33 @@
         }
       }
     },
-    "/email/messages/restore": {
+    "/email/messages/send": {
       "post": {
-        "operationId": "email_restore",
+        "operationId": "email_send",
         "tags": [
           "Emails"
         ],
-        "summary": "Restore soft-deleted inbound emails",
-        "description": "### Overview\nRestores a batch of soft-deleted inbound emails from the trash, making them reappear in standard inbox lists.\n\n### When to Use\n- Use this endpoint to recover email messages that were trashed by mistake.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Accepts 1 to 100 email IDs. Already-active IDs are silently ignored.\n\n### Troubleshooting\n- **401 Unauthorized**: Invalid token.\n- **400 Bad Request**: Malformed request or batch limit exceeded.",
+        "summary": "Send an outbound email",
+        "description": "### Overview\nSubmits a single outbound email for delivery from one of the caller's active aliases. All details, including attachments (inline base64 blobs or references to existing inbound attachments), are verified before sending. Platform-domain aliases use Cloudflare Email Service; verified custom-domain aliases use pete-mail.\n\n### When to Use\n- Use this endpoint to send new standalone emails or to reply to threaded inbound messages.\n- Use this in automated agent pipelines (like calendar invite generation or notifications) and CLI email send utilities.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Size Limits**: Individual attachments must not exceed 5 MiB, and the total size of all attachments per send must be 25 MiB or less.\n- **Security**: Up to 10 attachments are allowed. Outbound files with dangerous executable extensions (such as `.exe`, `.bat`, `.com`, `.scr`, `.cmd`, `.jar`, `.js`) are strictly blocked.\n- **Daily Quotas**: Sending is protected by per-user (100 sends/day) and per-alias (50 sends/day) daily quotas. Exceeding them triggers `RATE_LIMITED` or `QUOTA_EXCEEDED` errors.\n- **Custom Domains**: Platform-domain aliases use Cloudflare Email Service. Verified custom-domain aliases are routed through pete-mail. Custom domains must have `status = verified` and `sending_status = verified` or the send returns `CUSTOM_DOMAIN_NOT_READY`.\n- **Idempotency**: A stable `idempotency_key` (1-200 characters) must be supplied. Retrying a send with identical content and the same key returns `idempotent_replay: true` without sending duplicates. Reusing the key with changed content returns 409 `IDEMPOTENCY_KEY_REUSED`.\n\n### Troubleshooting\n- **401 Unauthorized**: Active Bearer token is invalid or has expired.\n- **404 Not Found**: The requested `from_alias_email` does not exist or has been soft-deleted, or the referenced `in_reply_to_email_id` is missing or belongs to a different user.\n- **409 Conflict / IDEMPOTENCY_KEY_REUSED**: An identical `idempotency_key` was reused with modified request payload. Use a fresh unique key.\n- **409 Conflict / CUSTOM_DOMAIN_NOT_READY**: The sender uses a custom domain that has not completed outbound sending verification.\n- **429 Too Many Requests / RATE_LIMITED**: The per-user rate limit or daily sending quota has been exceeded. Wait for quota reset.\n- **502 Bad Gateway**: The upstream outbound provider failed or rejected the message. The outbound row is persisted with `status: failed` along with provider-returned logs.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
         "x-cli": {
-          "command": "_internal",
+          "command": "_handwritten",
           "hidden": true
         },
         "x-codeSamples": [
           {
             "lang": "shell",
             "label": "curl",
-            "source": "curl -X POST https://api.wspc.ai/email/messages/restore \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"ids\":[\"eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F\"]}'"
+            "source": "curl -X POST https://api.wspc.ai/email/messages/send \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"from_alias_email\":\"alice-shop@wspc.app\",\"to\":[\"alice@example.com\"],\"subject\":\"Welcome\",\"text\":\"Hi Alice\",\"idempotency_key\":\"retry-20260601-001\"}'"
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc email send \\\n  --from alice-shop@wspc.app \\\n  --to alice@example.com \\\n  --subject \"Welcome to WSPC\" \\\n  --text \"Hi Alice — welcome aboard.\" \\\n  --attach ./report.pdf \\\n  --idempotency-key retry-20260601-001"
           }
         ],
         "requestBody": {
@@ -17801,25 +19284,41 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/BatchIdsBody"
+                "$ref": "#/components/schemas/SendEmailBody"
               },
               "examples": {
                 "minimal": {
-                  "summary": "Single id",
+                  "summary": "Fresh send — required fields only",
                   "value": {
-                    "ids": [
-                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
-                    ]
+                    "from_alias_email": "alice-shop@wspc.app",
+                    "to": [
+                      "alice@example.com"
+                    ],
+                    "subject": "Welcome to WSPC",
+                    "text": "Hi Alice — welcome aboard.",
+                    "idempotency_key": "retry-20260601-001"
+                  }
+                },
+                "reply": {
+                  "summary": "Threaded reply — to/subject derived from the inbound message",
+                  "value": {
+                    "from_alias_email": "alice-shop@wspc.app",
+                    "in_reply_to_email_id": "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                    "text": "Thanks — replying inline.",
+                    "idempotency_key": "reply-20260601-001"
                   }
                 },
                 "full": {
-                  "summary": "Multiple ids (up to 100 per call)",
+                  "summary": "Multi-recipient with explicit subject",
                   "value": {
-                    "ids": [
-                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3G",
-                      "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3H"
-                    ]
+                    "from_alias_email": "alice-shop@wspc.app",
+                    "to": [
+                      "alice@example.com",
+                      "bob@example.com"
+                    ],
+                    "subject": "Lunch with Alice",
+                    "text": "Confirming lunch — see you at the lobby at 12:30.",
+                    "idempotency_key": "lunch-confirm-20260601"
                   }
                 }
               }
@@ -17828,35 +19327,195 @@
         },
         "responses": {
           "200": {
-            "description": "Bulk restore result. `restored` counts state changes only.",
+            "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.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/RestoreBatchResponse"
+                  "$ref": "#/components/schemas/SendEmailResponse"
                 },
                 "examples": {
                   "happyPath": {
-                    "summary": "All ids matched and changed state",
+                    "summary": "Fresh send succeeded",
                     "value": {
-                      "restored": 2,
-                      "not_found": []
+                      "email": {
+                        "id": "out_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                        "org_id": "org_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                        "user_id": "usr_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                        "from_alias_email": "alice-shop@wspc.app",
+                        "from_addr": "alice-shop@wspc.app",
+                        "to": [
+                          "alice@example.com"
+                        ],
+                        "subject": "Welcome to WSPC",
+                        "text_body": "Hi Alice — welcome aboard.",
+                        "message_id": "<01HW3K4N9V5G6Z8C2Q7B1Y0M3G@wspc.app>",
+                        "provider": "cloudflare-email-service",
+                        "request_hash": "sha256:abc...",
+                        "status": "sent",
+                        "idempotency_key": "retry-20260601-001",
+                        "submitted_at": 1748736000500,
+                        "created_at": 1748736000000,
+                        "updated_at": 1748736000500
+                      },
+                      "idempotent_replay": false
                     }
                   },
-                  "partial": {
-                    "summary": "Some ids unknown to this user",
+                  "replay": {
+                    "summary": "Idempotent replay — provider not re-invoked",
                     "value": {
-                      "restored": 1,
-                      "not_found": [
-                        "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3X"
+                      "email": {
+                        "id": "out_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                        "org_id": "org_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                        "user_id": "usr_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
+                        "from_alias_email": "alice-shop@wspc.app",
+                        "from_addr": "alice-shop@wspc.app",
+                        "to": [
+                          "alice@example.com"
+                        ],
+                        "subject": "Welcome to WSPC",
+                        "text_body": "Hi Alice — welcome aboard.",
+                        "message_id": "<01HW3K4N9V5G6Z8C2Q7B1Y0M3G@wspc.app>",
+                        "provider": "cloudflare-email-service",
+                        "request_hash": "sha256:abc...",
+                        "status": "sent",
+                        "idempotency_key": "retry-20260601-001",
+                        "submitted_at": 1748736000500,
+                        "created_at": 1748736000000,
+                        "updated_at": 1748736000500
+                      },
+                      "idempotent_replay": true
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
+            "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": {
+                  "validationError": {
+                    "summary": "Body failed schema validation",
+                    "value": {
+                      "error": {
+                        "code": "VALIDATION_ERROR",
+                        "message": "title must not be empty"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "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": "`from_alias_email` is unknown / soft-deleted, or `in_reply_to_email_id` is not visible to the caller.",
+            "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"
+                  ]
                 }
               }
             }
           },
-          "400": {
-            "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
+          "409": {
+            "description": "Either an earlier send under this `idempotency_key` had different content, or the sender custom domain has not completed outbound sending verification.",
             "content": {
               "application/json": {
                 "schema": {
@@ -17885,23 +19544,12 @@
                   "required": [
                     "error"
                   ]
-                },
-                "examples": {
-                  "validationError": {
-                    "summary": "Body failed schema validation",
-                    "value": {
-                      "error": {
-                        "code": "VALIDATION_ERROR",
-                        "message": "title must not be empty"
-                      }
-                    }
-                  }
                 }
               }
             }
           },
-          "401": {
-            "description": "Authentication is required but missing or invalid. The Bearer token (API key or OAuth access token) was absent, malformed, or rejected.",
+          "429": {
+            "description": "Either the middleware send rate limit (`RATE_LIMITED`), the per-user daily cap of 100 sends (`RATE_LIMITED`), or the per-alias daily cap of 50 sends (`QUOTA_EXCEEDED`).",
             "content": {
               "application/json": {
                 "schema": {
@@ -17930,23 +19578,12 @@
                   "required": [
                     "error"
                   ]
-                },
-                "examples": {
-                  "authRequired": {
-                    "summary": "Missing Authorization header",
-                    "value": {
-                      "error": {
-                        "code": "AUTH_REQUIRED",
-                        "message": "missing bearer token"
-                      }
-                    }
-                  }
                 }
               }
             }
           },
-          "429": {
-            "description": "Rate limit exceeded. Retry after the duration in `error.extra.retry_after_seconds`. `limit_kind` identifies which bucket was exhausted.",
+          "500": {
+            "description": "Unhandled server error. The request was well-formed but the service failed unexpectedly. Safe to retry idempotent operations.",
             "content": {
               "application/json": {
                 "schema": {
@@ -17977,16 +19614,12 @@
                   ]
                 },
                 "examples": {
-                  "rateLimited": {
-                    "summary": "Per-key rate limit hit",
+                  "internalError": {
+                    "summary": "Unhandled exception",
                     "value": {
                       "error": {
-                        "code": "RATE_LIMITED",
-                        "message": "rate limit exceeded",
-                        "extra": {
-                          "retry_after_seconds": 60,
-                          "limit_kind": "authenticated_per_key"
-                        }
+                        "code": "INTERNAL_ERROR",
+                        "message": "internal error"
                       }
                     }
                   }
@@ -17994,8 +19627,8 @@
               }
             }
           },
-          "500": {
-            "description": "Unhandled server error. The request was well-formed but the service failed unexpectedly. Safe to retry idempotent operations.",
+          "502": {
+            "description": "The upstream email provider rejected the message. The row is persisted with `status: failed` and `error_code` / `error_message` set.",
             "content": {
               "application/json": {
                 "schema": {
@@ -18024,17 +19657,6 @@
                   "required": [
                     "error"
                   ]
-                },
-                "examples": {
-                  "internalError": {
-                    "summary": "Unhandled exception",
-                    "value": {
-                      "error": {
-                        "code": "INTERNAL_ERROR",
-                        "message": "internal error"
-                      }
-                    }
-                  }
                 }
               }
             }
@@ -18042,140 +19664,128 @@
         }
       }
     },
-    "/email/messages/send": {
+    "/email/domains/{domain}/verify": {
       "post": {
-        "operationId": "email_send",
+        "operationId": "email_domain_verify",
         "tags": [
-          "Emails"
+          "EmailDomains"
         ],
-        "summary": "Send an outbound email",
-        "description": "### Overview\nSubmits a single outbound email for delivery from one of the caller's active aliases. All details, including attachments (inline base64 blobs or references to existing inbound attachments), are verified before sending. Platform-domain aliases use Cloudflare Email Service; verified custom-domain aliases use pete-mail.\n\n### When to Use\n- Use this endpoint to send new standalone emails or to reply to threaded inbound messages.\n- Use this in automated agent pipelines (like calendar invite generation or notifications) and CLI email send utilities.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Size Limits**: Individual attachments must not exceed 5 MiB, and the total size of all attachments per send must be 25 MiB or less.\n- **Security**: Up to 10 attachments are allowed. Outbound files with dangerous executable extensions (such as `.exe`, `.bat`, `.com`, `.scr`, `.cmd`, `.jar`, `.js`) are strictly blocked.\n- **Daily Quotas**: Sending is protected by per-user (100 sends/day) and per-alias (50 sends/day) daily quotas. Exceeding them triggers `RATE_LIMITED` or `QUOTA_EXCEEDED` errors.\n- **Custom Domains**: Platform-domain aliases use Cloudflare Email Service. Verified custom-domain aliases are routed through pete-mail. Custom domains must have `status = verified` and `sending_status = verified` or the send returns `CUSTOM_DOMAIN_NOT_READY`.\n- **Idempotency**: A stable `idempotency_key` (1-200 characters) must be supplied. Retrying a send with identical content and the same key returns `idempotent_replay: true` without sending duplicates. Reusing the key with changed content returns 409 `IDEMPOTENCY_KEY_REUSED`.\n\n### Troubleshooting\n- **401 Unauthorized**: Active Bearer token is invalid or has expired.\n- **404 Not Found**: The requested `from_alias_email` does not exist or has been soft-deleted, or the referenced `in_reply_to_email_id` is missing or belongs to a different user.\n- **409 Conflict / IDEMPOTENCY_KEY_REUSED**: An identical `idempotency_key` was reused with modified request payload. Use a fresh unique key.\n- **409 Conflict / CUSTOM_DOMAIN_NOT_READY**: The sender uses a custom domain that has not completed outbound sending verification.\n- **429 Too Many Requests / RATE_LIMITED**: The per-user rate limit or daily sending quota has been exceeded. Wait for quota reset.\n- **502 Bad Gateway**: The upstream outbound provider failed or rejected the message. The outbound row is persisted with `status: failed` along with provider-returned logs.",
+        "summary": "Verify a custom domain with the provider",
+        "description": "### Overview\nTriggers an upstream provider verification attempt for one custom email domain, refreshes the cached DNS records/status in D1, and returns the updated row.\nThis route refreshes DNS registration and verification state. Custom-domain aliases require `status`, `sending_status`, and `receiving_status` to all be `verified`.\n\n### When to Use\n- Use this after publishing the required DNS records, or whenever you want to refresh cached provider state explicitly.\n- If the provider verify call returns incomplete DNS records, the worker performs a follow-up provider read before responding.\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 live provider calls.\n- Verification is asynchronous provider work; a successful response may still report `status: pending`.\n- `status: verified` plus `sending_status: verified` enables custom-domain outbound send for active aliases; `receiving_status: verified` is also required before new custom-domain aliases can be created.\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 or belongs to another organization.\n- **502 Bad Gateway / DOMAIN_PROVIDER_ERROR**: Provider verification failed, timed out, or credentials are missing.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
         "x-cli": {
-          "command": "_handwritten",
-          "hidden": true
+          "command": "domain verify",
+          "positional": [
+            "domain"
+          ],
+          "display": {
+            "shape": "object",
+            "format": {
+              "created_at": "relative-time",
+              "updated_at": "relative-time",
+              "verified_at": "relative-time"
+            },
+            "dataPath": "domain"
+          }
         },
         "x-codeSamples": [
           {
             "lang": "shell",
             "label": "curl",
-            "source": "curl -X POST https://api.wspc.ai/email/messages/send \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"from_alias_email\":\"alice-shop@wspc.app\",\"to\":[\"alice@example.com\"],\"subject\":\"Welcome\",\"text\":\"Hi Alice\",\"idempotency_key\":\"retry-20260601-001\"}'"
+            "source": "curl -X POST https://api.wspc.ai/email/domains/mail.example.com/verify \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
           },
           {
             "lang": "bash",
             "label": "wspc CLI",
-            "source": "wspc email send \\\n  --from alice-shop@wspc.app \\\n  --to alice@example.com \\\n  --subject \"Welcome to WSPC\" \\\n  --text \"Hi Alice — welcome aboard.\" \\\n  --attach ./report.pdf \\\n  --idempotency-key retry-20260601-001"
+            "source": "wspc email domain verify mail.example.com"
           }
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/SendEmailBody"
-              },
-              "examples": {
-                "minimal": {
-                  "summary": "Fresh send — required fields only",
-                  "value": {
-                    "from_alias_email": "alice-shop@wspc.app",
-                    "to": [
-                      "alice@example.com"
-                    ],
-                    "subject": "Welcome to WSPC",
-                    "text": "Hi Alice — welcome aboard.",
-                    "idempotency_key": "retry-20260601-001"
-                  }
-                },
-                "reply": {
-                  "summary": "Threaded reply — to/subject derived from the inbound message",
-                  "value": {
-                    "from_alias_email": "alice-shop@wspc.app",
-                    "in_reply_to_email_id": "eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                    "text": "Thanks — replying inline.",
-                    "idempotency_key": "reply-20260601-001"
-                  }
-                },
-                "full": {
-                  "summary": "Multi-recipient with explicit subject",
-                  "value": {
-                    "from_alias_email": "alice-shop@wspc.app",
-                    "to": [
-                      "alice@example.com",
-                      "bob@example.com"
-                    ],
-                    "subject": "Lunch with Alice",
-                    "text": "Confirming lunch — see you at the lobby at 12:30.",
-                    "idempotency_key": "lunch-confirm-20260601"
-                  }
-                }
-              }
-            }
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Custom domain hostname path parameter. URL-encode if your client requires it."
+            },
+            "required": true,
+            "description": "Custom domain hostname path parameter. URL-encode if your client requires it.",
+            "name": "domain",
+            "in": "path"
           }
-        },
+        ],
         "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.",
+            "description": "Updated cached provider state after a verification attempt, including ownership, sending readiness, and receiving readiness.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SendEmailResponse"
+                  "$ref": "#/components/schemas/EmailDomainObjectResponse"
                 },
                 "examples": {
                   "happyPath": {
-                    "summary": "Fresh send succeeded",
-                    "value": {
-                      "email": {
-                        "id": "out_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                        "org_id": "org_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                        "user_id": "usr_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                        "from_alias_email": "alice-shop@wspc.app",
-                        "from_addr": "alice-shop@wspc.app",
-                        "to": [
-                          "alice@example.com"
+                    "summary": "Domain ownership and sending verified; receiving is not ready yet",
+                    "value": {
+                      "domain": {
+                        "domain": "mail.example.com",
+                        "status": "verified",
+                        "sending_status": "verified",
+                        "receiving_status": "disabled",
+                        "records": [
+                          {
+                            "type": "TXT",
+                            "name": "mail.example.com",
+                            "value": "pm-domain-verification=abc123",
+                            "status": "verified",
+                            "ttl": 3600,
+                            "purpose": "identity_verification"
+                          },
+                          {
+                            "type": "CNAME",
+                            "name": "selector1._domainkey.mail.example.com",
+                            "value": "selector1.domainkey.example.net",
+                            "status": "verified",
+                            "purpose": "dkim"
+                          }
                         ],
-                        "subject": "Welcome to WSPC",
-                        "text_body": "Hi Alice — welcome aboard.",
-                        "message_id": "<01HW3K4N9V5G6Z8C2Q7B1Y0M3G@wspc.app>",
-                        "provider": "cloudflare-email-service",
-                        "request_hash": "sha256:abc...",
-                        "status": "sent",
-                        "idempotency_key": "retry-20260601-001",
-                        "submitted_at": 1748736000500,
-                        "created_at": 1748736000000,
-                        "updated_at": 1748736000500
-                      },
-                      "idempotent_replay": false
-                    }
-                  },
-                  "replay": {
-                    "summary": "Idempotent replay — provider not re-invoked",
-                    "value": {
-                      "email": {
-                        "id": "out_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                        "org_id": "org_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                        "user_id": "usr_01HW3K4N9V5G6Z8C2Q7B1Y0M3F",
-                        "from_alias_email": "alice-shop@wspc.app",
-                        "from_addr": "alice-shop@wspc.app",
-                        "to": [
-                          "alice@example.com"
+                        "region": "us-east-1",
+                        "created_at": 1780166400000,
+                        "updated_at": 1780167000000,
+                        "verified_at": 1780167000000
+                      }
+                    }
+                  },
+                  "stillPending": {
+                    "summary": "Provider accepted verify request but DNS is not ready yet",
+                    "value": {
+                      "domain": {
+                        "domain": "mail.example.com",
+                        "status": "pending",
+                        "sending_status": "pending",
+                        "receiving_status": "pending",
+                        "records": [
+                          {
+                            "type": "TXT",
+                            "name": "mail.example.com",
+                            "value": "pm-domain-verification=abc123",
+                            "status": "pending",
+                            "ttl": 3600,
+                            "purpose": "identity_verification"
+                          },
+                          {
+                            "type": "CNAME",
+                            "name": "selector1._domainkey.mail.example.com",
+                            "value": "selector1.domainkey.example.net",
+                            "status": "pending",
+                            "purpose": "dkim"
+                          }
                         ],
-                        "subject": "Welcome to WSPC",
-                        "text_body": "Hi Alice — welcome aboard.",
-                        "message_id": "<01HW3K4N9V5G6Z8C2Q7B1Y0M3G@wspc.app>",
-                        "provider": "cloudflare-email-service",
-                        "request_hash": "sha256:abc...",
-                        "status": "sent",
-                        "idempotency_key": "retry-20260601-001",
-                        "submitted_at": 1748736000500,
-                        "created_at": 1748736000000,
-                        "updated_at": 1748736000500
-                      },
-                      "idempotent_replay": true
+                        "region": "us-east-1",
+                        "created_at": 1780166400000,
+                        "updated_at": 1780166400000
+                      }
                     }
                   }
                 }
@@ -18183,7 +19793,7 @@
             }
           },
           "400": {
-            "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
+            "description": "Malformed or platform-reserved domain hostname.",
             "content": {
               "application/json": {
                 "schema": {
@@ -18212,17 +19822,6 @@
                   "required": [
                     "error"
                   ]
-                },
-                "examples": {
-                  "validationError": {
-                    "summary": "Body failed schema validation",
-                    "value": {
-                      "error": {
-                        "code": "VALIDATION_ERROR",
-                        "message": "title must not be empty"
-                      }
-                    }
-                  }
                 }
               }
             }
@@ -18273,7 +19872,7 @@
             }
           },
           "404": {
-            "description": "`from_alias_email` is unknown / soft-deleted, or `in_reply_to_email_id` is not visible to the caller.",
+            "description": "The domain was not found for the caller organization.",
             "content": {
               "application/json": {
                 "schema": {
@@ -18306,8 +19905,8 @@
               }
             }
           },
-          "409": {
-            "description": "Either an earlier send under this `idempotency_key` had different content, or the sender custom domain has not completed outbound sending verification.",
+          "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": {
@@ -18336,40 +19935,21 @@
                   "required": [
                     "error"
                   ]
-                }
-              }
-            }
-          },
-          "429": {
-            "description": "Either the middleware send rate limit (`RATE_LIMITED`), the per-user daily cap of 100 sends (`RATE_LIMITED`), or the per-alias daily cap of 50 sends (`QUOTA_EXCEEDED`).",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "error": {
-                      "type": "object",
-                      "properties": {
-                        "code": {
-                          "type": "string"
-                        },
-                        "message": {
-                          "type": "string"
-                        },
+                },
+                "examples": {
+                  "rateLimited": {
+                    "summary": "Per-key rate limit hit",
+                    "value": {
+                      "error": {
+                        "code": "RATE_LIMITED",
+                        "message": "rate limit exceeded",
                         "extra": {
-                          "type": "object",
-                          "additionalProperties": {}
+                          "retry_after_seconds": 60,
+                          "limit_kind": "authenticated_per_key"
                         }
-                      },
-                      "required": [
-                        "code",
-                        "message"
-                      ]
+                      }
                     }
-                  },
-                  "required": [
-                    "error"
-                  ]
+                  }
                 }
               }
             }
@@ -18420,7 +20000,7 @@
             }
           },
           "502": {
-            "description": "The upstream email provider rejected the message. The row is persisted with `status: failed` and `error_code` / `error_message` set.",
+            "description": "The upstream provider call failed or provider credentials are missing.",
             "content": {
               "application/json": {
                 "schema": {
@@ -31031,6 +32611,10 @@
       "name": "EmailAliases",
       "description": "User-managed @wspc.app email aliases that route inbound mail to the user's inbox."
     },
+    {
+      "name": "EmailDomains",
+      "description": "EmailDomains endpoints."
+    },
     {
       "name": "Emails",
       "description": "Inbound and outbound email messages with attachment support."