{ "components": { "schemas": { "Error": { "description": "Standard error envelope. `code` is a stable machine-readable string.", "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "error": { "type": "string" } }, "required": [ "error", "code" ], "type": "object" } }, "securitySchemes": { "BearerApiKey": { "description": "ReplyLayer API key: `Authorization: Bearer rly_live_.`.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "The ReplyLayer REST API for AI agents — send, receive, read, and reply to email with built-in security scanning. Authenticate with an API key (`Authorization: Bearer rly_live_.`). This is the customer contract only; operator/admin endpoints and the session-cookie dashboard surface are not part of this spec.", "title": "ReplyLayer API", "version": "1.0.0" }, "openapi": "3.0.3", "paths": { "/v1/account/policy": { "get": { "operationId": "getV1AccountPolicy", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "custom_daily_send_limit": { "nullable": true, "type": "integer" }, "default_policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted", null ], "nullable": true, "type": "string" }, "resolved_default_policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted" ], "type": "string" } }, "required": [ "custom_daily_send_limit", "default_policy_mode", "resolved_default_policy_mode" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Read the account policy (daily cap, default mode for new mailboxes)", "tags": [ "policy" ] }, "patch": { "operationId": "patchV1AccountPolicy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "custom_daily_send_limit": { "minimum": 1, "nullable": true, "type": "integer" }, "default_policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted", null ], "nullable": true, "type": "string" }, "reauth_challenge": { "type": "string" }, "reauth_token": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "custom_daily_send_limit": { "nullable": true, "type": "integer" }, "default_policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted", null ], "nullable": true, "type": "string" }, "resolved_default_policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted" ], "type": "string" } }, "required": [ "custom_daily_send_limit", "default_policy_mode", "resolved_default_policy_mode" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Update the account daily cap / default mode (loosening requires a dashboard session)", "tags": [ "policy" ] } }, "/v1/accounts": { "delete": { "operationId": "deleteV1Accounts", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "status": { "enum": [ "deleted" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Delete the current account", "tags": [ "account" ] }, "get": { "operationId": "getV1Accounts", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_id": { "type": "string" }, "agent_delete_messages_enabled": { "type": "boolean" }, "email": { "type": "string" }, "status": { "type": "string" }, "tier": { "type": "string" } }, "required": [ "account_id", "email", "status", "tier" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get the current account", "tags": [ "account" ] } }, "/v1/accounts/agent-delete-policy": { "post": { "operationId": "postV1AccountsAgentDeletePolicy", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_delete_messages_enabled": { "type": "boolean" } }, "required": [ "agent_delete_messages_enabled" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Configure the agent account-deletion policy", "tags": [ "account" ] } }, "/v1/accounts/api-keys": { "get": { "operationId": "getV1AccountsApiKeys", "parameters": [ { "in": "query", "name": "include_revoked", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "keys": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "instruction_trust_enabled": { "type": "boolean" }, "label": { "nullable": true, "type": "string" }, "last_used_at": { "format": "date-time", "nullable": true, "type": "string" }, "mailbox_ids": { "items": { "type": "string" }, "type": "array" }, "prefix": { "type": "string" }, "revoked_at": { "format": "date-time", "nullable": true, "type": "string" }, "revoked_by": { "nullable": true, "type": "string" }, "role": { "enum": [ "admin", "agent", null ], "nullable": true, "type": "string" }, "status": { "enum": [ "active", "revoked" ], "type": "string" } }, "required": [ "id", "prefix", "status", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "keys" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List API keys", "tags": [ "account" ] }, "post": { "operationId": "postV1AccountsApiKeys", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "label": { "maxLength": 100, "type": "string" }, "mailbox_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array", "uniqueItems": true }, "role": { "enum": [ "admin", "agent" ], "type": "string" } }, "required": [ "role" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "api_key": { "type": "string" }, "id": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "mailbox_ids": { "items": { "type": "string" }, "type": "array" }, "role": { "enum": [ "admin", "agent" ], "type": "string" } }, "required": [ "id", "api_key", "role", "mailbox_ids" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Create an API key", "tags": [ "account" ] } }, "/v1/accounts/api-keys/rotate": { "post": { "operationId": "postV1AccountsApiKeysRotate", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "api_key": { "type": "string" } }, "required": [ "api_key" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Rotate all API keys (admin)", "tags": [ "account" ] } }, "/v1/accounts/api-keys/{id}": { "delete": { "operationId": "deleteV1AccountsApiKeysById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "revoked_at": { "type": "string" }, "revoked_by": { "type": "string" }, "status": { "enum": [ "revoked" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Revoke an API key", "tags": [ "account" ] }, "patch": { "operationId": "patchV1AccountsApiKeysById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "mailbox_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "mailbox_ids" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "label": { "nullable": true, "type": "string" }, "mailbox_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "role": { "enum": [ "agent" ], "type": "string" } }, "required": [ "id", "role", "label", "mailbox_ids" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Update an agent API key's mailbox bindings", "tags": [ "account" ] } }, "/v1/accounts/export": { "get": { "operationId": "getV1AccountsExport", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Export account data (GDPR/CCPA, admin)", "tags": [ "account" ] } }, "/v1/accounts/quota": { "get": { "operationId": "getV1AccountsQuota", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "bound_mailbox_ids": { "items": { "type": "string" }, "type": "array" }, "reset_at": { "type": "string" }, "scope": { "enum": [ "admin", "agent" ], "type": "string" }, "sends_remaining": { "minimum": 0, "type": "integer" }, "today": { "properties": { "count": { "type": "integer" }, "day": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "count", "limit", "day" ], "type": "object" }, "warmup": { "properties": { "reason": { "type": "string" }, "shared_domain_daily_limit": { "type": "integer" }, "until": { "type": "string" }, "velocity_gate_mode": { "enum": [ "log_only", "enforced" ], "type": "string" } }, "required": [ "until", "shared_domain_daily_limit", "velocity_gate_mode", "reason" ], "type": "object" } }, "required": [ "today", "sends_remaining", "reset_at", "scope", "bound_mailbox_ids" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get the effective send quota", "tags": [ "account" ] } }, "/v1/accounts/signup": { "post": { "operationId": "postV1AccountsSignup", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accept_terms": { "enum": [ true ], "type": "boolean" }, "accept_web_risk_version": { "maxLength": 32, "minLength": 1, "type": "string" }, "cli_signup_code": { "maxLength": 128, "minLength": 16, "type": "string" }, "email": { "format": "email", "type": "string" }, "invite_code": { "minLength": 1, "type": "string" }, "phone_number": { "maxLength": 32, "minLength": 8, "type": "string" } }, "required": [ "email", "phone_number", "accept_terms" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_id": { "type": "string" }, "api_key": { "type": "string" }, "email_verification_required": { "type": "boolean" }, "message": { "type": "string" }, "phone_number_masked": { "nullable": true, "type": "string" }, "phone_verification_required": { "type": "boolean" }, "sms_delivery_status": { "enum": [ "sent", "pending", "not_required" ], "type": "string" }, "verification_required": { "type": "boolean" } }, "required": [ "account_id", "api_key" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: SIGNUP_RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "security": [], "summary": "Create an account (public, invite-gated)", "tags": [ "account" ] } }, "/v1/accounts/url-reputation": { "post": { "operationId": "postV1AccountsUrlReputation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accept_web_risk_version": { "maxLength": 32, "minLength": 1, "type": "string" } }, "required": [ "accept_web_risk_version" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "disclosure": { "additionalProperties": false, "properties": { "advisory_url": { "type": "string" }, "notice": { "type": "string" } }, "required": [ "notice", "advisory_url" ], "type": "object" }, "url_reputation": { "additionalProperties": false, "properties": { "accepted_version": { "nullable": true, "type": "string" }, "active": { "type": "boolean" }, "current_version": { "type": "string" }, "privacy_ok": { "type": "boolean" } }, "required": [ "active", "accepted_version", "current_version", "privacy_ok" ], "type": "object" } }, "required": [ "url_reputation", "disclosure" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Enable malicious-link scanning", "tags": [ "account" ] } }, "/v1/accounts/usage": { "get": { "operationId": "getV1AccountsUsage", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "health": { "properties": { "bounce": { "properties": { "action_hint": { "nullable": true, "type": "string" }, "basis_count": { "type": "number" }, "status": { "enum": [ "healthy", "watch", "at_risk", "insufficient_data" ], "type": "string" }, "summary": { "type": "string" }, "value": { "type": "number" }, "window": { "type": "string" } }, "type": "object" }, "complaint": { "properties": { "action_hint": { "nullable": true, "type": "string" }, "basis_count": { "type": "number" }, "status": { "enum": [ "healthy", "watch", "at_risk", "insufficient_data" ], "type": "string" }, "summary": { "type": "string" }, "value": { "type": "number" }, "window": { "type": "string" } }, "type": "object" } }, "type": "object" }, "history": { "items": { "properties": { "count": { "type": "number" }, "day": { "type": "string" } }, "required": [ "day", "count" ], "type": "object" }, "type": "array" }, "mailbox_count": { "type": "number" }, "mailbox_limit": { "type": "number" }, "pending_review_count": { "minimum": 0, "type": "integer" }, "rates": { "properties": { "bounce_30d": { "type": "number" }, "bounce_7d": { "type": "number" }, "complaint_24h": { "type": "number" }, "complaint_7d": { "type": "number" }, "delivery_7d": { "type": "number" }, "quarantine_24h": { "type": "number" } }, "type": "object" }, "storage": { "properties": { "breakdown": { "properties": { "derivative_bytes": { "minimum": 0, "type": "integer" }, "raw_mime_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "raw_mime_bytes", "derivative_bytes" ], "type": "object" }, "limit_bytes": { "oneOf": [ { "minimum": 0, "type": "integer" }, { "nullable": true } ] }, "percent_used": { "oneOf": [ { "minimum": 0, "type": "number" }, { "nullable": true } ] }, "state": { "enum": [ "normal", "warning", "near_full", "over_limit" ], "type": "string" }, "used_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "used_bytes", "limit_bytes", "percent_used", "state", "breakdown" ], "type": "object" }, "tier": { "type": "string" }, "today": { "properties": { "count": { "type": "number" }, "day": { "type": "string" }, "limit": { "type": "number" } }, "required": [ "count", "limit", "day" ], "type": "object" }, "trust": { "properties": { "byod_acceleration": { "properties": { "clean_send_progress": { "properties": { "bounce_rate": { "properties": { "current": { "minimum": 0, "type": "number" }, "met": { "type": "boolean" }, "required": { "minimum": 0, "type": "number" } }, "required": [ "current", "required", "met" ], "type": "object" }, "bounce_rate_7d": { "properties": { "current": { "minimum": 0, "type": "number" }, "met": { "type": "boolean" }, "required": { "minimum": 0, "type": "number" } }, "required": [ "current", "required", "met" ], "type": "object" }, "complaint_rate": { "properties": { "current": { "minimum": 0, "type": "number" }, "met": { "type": "boolean" }, "required": { "minimum": 0, "type": "number" } }, "required": [ "current", "required", "met" ], "type": "object" }, "payment_method": { "properties": { "met": { "type": "boolean" } }, "required": [ "met" ], "type": "object" }, "quarantine_rate_24h": { "properties": { "current": { "minimum": 0, "type": "number" }, "met": { "type": "boolean" }, "required": { "minimum": 0, "type": "number" } }, "required": [ "current", "required", "met" ], "type": "object" }, "recent_sends": { "properties": { "current": { "minimum": 0, "type": "integer" }, "met": { "type": "boolean" }, "required": { "minimum": 1, "type": "integer" } }, "required": [ "current", "required", "met" ], "type": "object" } }, "required": [ "recent_sends", "bounce_rate", "complaint_rate", "bounce_rate_7d", "quarantine_rate_24h", "payment_method" ], "type": "object" }, "hours_until_eligible": { "nullable": true, "type": "integer" }, "status": { "enum": [ "eligible", "pending_24h", "pending_clean_send", "not_eligible", "not_applicable" ], "type": "string" }, "verified_at": { "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "status", "verified_at", "hours_until_eligible" ], "type": "object" }, "level": { "type": "number" }, "next_promotion": { "oneOf": [ { "properties": { "eligible": { "type": "boolean" }, "requirements": { "additionalProperties": true, "type": "object" }, "target_level": { "type": "number" } }, "type": "object" }, { "nullable": true } ] } }, "type": "object" } }, "required": [ "today", "history", "mailbox_count", "mailbox_limit", "pending_review_count", "storage" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get account usage & limits (admin)", "tags": [ "account" ] } }, "/v1/accounts/{id}": { "delete": { "operationId": "deleteV1AccountsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "status": { "enum": [ "deleted" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Delete an account by id (self)", "tags": [ "account" ] } }, "/v1/attachments": { "post": { "operationId": "postV1Attachments", "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "The attachment bytes.", "format": "binary", "type": "string" }, "mailbox_id": { "description": "Target mailbox name or id.", "type": "string" } }, "required": [ "mailbox_id", "file" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "content_scan_status": { "enum": [ "pending", "clean", "flagged", "error" ], "type": "string" }, "content_type": { "type": "string" }, "filename": { "type": "string" }, "hash": { "type": "string" }, "id": { "type": "string" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "size": { "type": "integer" } }, "required": [ "id", "filename", "content_type", "size", "hash", "content_scan_status" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Stage an outbound attachment", "tags": [ "attachments" ] } }, "/v1/attachments/{id}": { "delete": { "operationId": "deleteV1AttachmentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Delete a staged attachment handle", "tags": [ "attachments" ] }, "get": { "operationId": "getV1AttachmentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "consumed_at": { "type": "string" }, "consumed_message_id": { "nullable": true, "type": "string" }, "content_scan_status": { "enum": [ "pending", "clean", "flagged", "error" ], "type": "string" }, "content_type": { "type": "string" }, "filename": { "type": "string" }, "hash": { "type": "string" }, "id": { "type": "string" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "size": { "type": "integer" }, "status": { "enum": [ "consumed" ], "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get a staged attachment handle", "tags": [ "attachments" ] } }, "/v1/domains": { "post": { "operationId": "postV1Domains", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "domain": { "maxLength": 253, "minLength": 4, "type": "string" }, "self_hosted_config": { "additionalProperties": false, "properties": { "imap": { "additionalProperties": false, "properties": { "host": { "minLength": 1, "type": "string" }, "password": { "minLength": 1, "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "security": { "enum": [ "starttls", "tls" ], "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "host", "port", "security", "username", "password" ], "type": "object" }, "network_mode": { "enum": [ "public", "tailnet" ], "type": "string" }, "smtp": { "additionalProperties": false, "properties": { "host": { "minLength": 1, "type": "string" }, "password": { "minLength": 1, "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "security": { "enum": [ "starttls", "tls" ], "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "host", "port", "security", "username", "password" ], "type": "object" } }, "required": [ "smtp", "imap", "network_mode" ], "type": "object" }, "transport_mode": { "enum": [ "mailgun", "ses", "self_hosted" ], "type": "string" } }, "required": [ "domain" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "expires_at": { "nullable": true, "type": "string" } }, "required": [ "error", "code" ], "type": "object" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Register a custom domain", "tags": [ "domains" ] } }, "/v1/domains/{id}/self-hosted-config": { "patch": { "operationId": "patchV1DomainsByIdSelfHostedConfig", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "imap": { "additionalProperties": false, "properties": { "host": { "minLength": 1, "type": "string" }, "password": { "minLength": 1, "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "security": { "enum": [ "starttls", "tls" ], "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "type": "object" }, "network_mode": { "enum": [ "public", "tailnet" ], "type": "string" }, "smtp": { "additionalProperties": false, "properties": { "host": { "minLength": 1, "type": "string" }, "password": { "minLength": 1, "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "security": { "enum": [ "starttls", "tls" ], "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "type": "object" }, "tailnet_auth_key": { "minLength": 1, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Update self-hosted transport config (admin)", "tags": [ "domains" ] } }, "/v1/domains/{id}/self-hosted-recheck": { "post": { "operationId": "postV1DomainsByIdSelfHostedRecheck", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Re-probe self-hosted transport health (admin)", "tags": [ "domains" ] } }, "/v1/drafts": { "post": { "operationId": "postV1Drafts", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachment_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array", "uniqueItems": true }, "body": { "maxLength": 1000000, "minLength": 1, "type": "string" }, "html": { "maxLength": 1000000, "type": "string" }, "in_reply_to_message_id": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" }, "mailbox_id": { "minLength": 1, "type": "string" }, "send_at": { "type": "string" }, "subaddress_instance_id": { "maxLength": 128, "minLength": 1, "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$", "type": "string" }, "subaddress_mode": { "enum": [ "reply_to", "from", "none" ], "type": "string" }, "subject": { "maxLength": 998, "pattern": "^[^\\r\\n]*$", "type": "string" }, "thread_id": { "minLength": 1, "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "body" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "attachments": { "items": { "additionalProperties": false, "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "policy_action": { "type": "string" }, "size": { "type": "number" }, "upload_id": { "nullable": true, "type": "string" } }, "required": [ "filename", "content_type", "size" ], "type": "object" }, "type": "array" }, "body": { "properties": { "char_count": { "type": "integer" }, "content": { "nullable": true, "type": "string" }, "format": { "enum": [ "text", "html" ], "type": "string" }, "returned_char_count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "format", "content", "char_count", "returned_char_count", "truncated" ], "type": "object" }, "compose_held_at": { "format": "date-time", "nullable": true, "type": "string" }, "compose_held_decision": { "enum": [ "quarantine", "block", "require_human_approval", null ], "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "in_reply_to": { "nullable": true, "type": "string" }, "last_dispatch_attempt_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_dispatch_error_code": { "nullable": true, "type": "string" }, "mailbox_id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "original_send_at": { "format": "date-time", "nullable": true, "type": "string" }, "recipient": { "type": "string" }, "releasable": { "type": "boolean" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "send_at": { "format": "date-time", "nullable": true, "type": "string" }, "send_attempts": { "type": "integer" }, "sender": { "type": "string" }, "state": { "enum": [ "draft", "available", "deleted" ], "type": "string" }, "subaddress_instance_id": { "nullable": true, "type": "string" }, "subaddress_mode": { "enum": [ "reply_to", "from", "none", null ], "nullable": true, "type": "string" }, "subject": { "type": "string" }, "thread_id": { "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "worst_decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "id", "mailbox_id", "state", "sender", "recipient", "subject", "body", "scan", "worst_decision", "send_attempts", "created_at", "updated_at" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Upstream failure (code: ATTACHMENT_FETCH_FAILED)" } }, "summary": "Create a draft", "tags": [ "drafts" ] } }, "/v1/drafts/{id}": { "delete": { "operationId": "deleteV1DraftsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: MAILBOX_ACCESS_DENIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Delete a draft", "tags": [ "drafts" ] }, "get": { "operationId": "getV1DraftsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "in": "query", "name": "body_format", "required": false, "schema": { "enum": [ "text", "html" ], "type": "string" } }, { "in": "query", "name": "body_page", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "view", "required": false, "schema": { "enum": [ "summary", "verbose" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "attachments": { "items": { "additionalProperties": false, "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "policy_action": { "type": "string" }, "size": { "type": "number" }, "upload_id": { "nullable": true, "type": "string" } }, "required": [ "filename", "content_type", "size" ], "type": "object" }, "type": "array" }, "body": { "properties": { "char_count": { "type": "integer" }, "content": { "nullable": true, "type": "string" }, "format": { "enum": [ "text", "html" ], "type": "string" }, "returned_char_count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "format", "content", "char_count", "returned_char_count", "truncated" ], "type": "object" }, "compose_held_at": { "format": "date-time", "nullable": true, "type": "string" }, "compose_held_decision": { "enum": [ "quarantine", "block", "require_human_approval", null ], "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "in_reply_to": { "nullable": true, "type": "string" }, "last_dispatch_attempt_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_dispatch_error_code": { "nullable": true, "type": "string" }, "mailbox_id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "original_send_at": { "format": "date-time", "nullable": true, "type": "string" }, "recipient": { "type": "string" }, "releasable": { "type": "boolean" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "send_at": { "format": "date-time", "nullable": true, "type": "string" }, "send_attempts": { "type": "integer" }, "sender": { "type": "string" }, "state": { "enum": [ "draft", "available", "deleted" ], "type": "string" }, "subaddress_instance_id": { "nullable": true, "type": "string" }, "subaddress_mode": { "enum": [ "reply_to", "from", "none", null ], "nullable": true, "type": "string" }, "subject": { "type": "string" }, "thread_id": { "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "worst_decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "id", "mailbox_id", "state", "sender", "recipient", "subject", "body", "scan", "worst_decision", "send_attempts", "created_at", "updated_at" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get a draft", "tags": [ "drafts" ] }, "patch": { "operationId": "patchV1DraftsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachment_ids": { "items": { "format": "uuid", "type": "string" }, "nullable": true, "type": "array", "uniqueItems": true }, "body": { "maxLength": 1000000, "minLength": 1, "type": "string" }, "html": { "maxLength": 1000000, "type": "string" }, "send_at": { "nullable": true, "type": "string" }, "subaddress_instance_id": { "maxLength": 128, "minLength": 1, "nullable": true, "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$", "type": "string" }, "subaddress_mode": { "enum": [ "reply_to", "from", "none", null ], "nullable": true, "type": "string" }, "subject": { "maxLength": 998, "pattern": "^[^\\r\\n]*$", "type": "string" }, "to": { "format": "email", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "attachments": { "items": { "additionalProperties": false, "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "policy_action": { "type": "string" }, "size": { "type": "number" }, "upload_id": { "nullable": true, "type": "string" } }, "required": [ "filename", "content_type", "size" ], "type": "object" }, "type": "array" }, "body": { "properties": { "char_count": { "type": "integer" }, "content": { "nullable": true, "type": "string" }, "format": { "enum": [ "text", "html" ], "type": "string" }, "returned_char_count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "format", "content", "char_count", "returned_char_count", "truncated" ], "type": "object" }, "compose_held_at": { "format": "date-time", "nullable": true, "type": "string" }, "compose_held_decision": { "enum": [ "quarantine", "block", "require_human_approval", null ], "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "in_reply_to": { "nullable": true, "type": "string" }, "last_dispatch_attempt_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_dispatch_error_code": { "nullable": true, "type": "string" }, "mailbox_id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "original_send_at": { "format": "date-time", "nullable": true, "type": "string" }, "recipient": { "type": "string" }, "releasable": { "type": "boolean" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "send_at": { "format": "date-time", "nullable": true, "type": "string" }, "send_attempts": { "type": "integer" }, "sender": { "type": "string" }, "state": { "enum": [ "draft", "available", "deleted" ], "type": "string" }, "subaddress_instance_id": { "nullable": true, "type": "string" }, "subaddress_mode": { "enum": [ "reply_to", "from", "none", null ], "nullable": true, "type": "string" }, "subject": { "type": "string" }, "thread_id": { "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "worst_decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "id", "mailbox_id", "state", "sender", "recipient", "subject", "body", "scan", "worst_decision", "send_attempts", "created_at", "updated_at" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict (code: ATTACHMENT_ALREADY_CONSUMED, DRAFT_ALREADY_SENT)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Upstream failure (code: ATTACHMENT_FETCH_FAILED)" } }, "summary": "Update a draft", "tags": [ "drafts" ] } }, "/v1/drafts/{id}/release-and-send": { "post": { "operationId": "postV1DraftsByIdReleaseAndSend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "override_reason": { "maxLength": 2000, "nullable": true, "type": "string" }, "release_source": { "enum": [ "compose_inline", "quarantine_page" ], "type": "string" } }, "required": [ "release_source" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message_id": { "type": "string" }, "status": { "enum": [ "sent", "blocked" ], "type": "string" } }, "required": [ "status", "message_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Release a held draft and send (not agent-callable)", "tags": [ "drafts" ] } }, "/v1/drafts/{id}/send": { "post": { "operationId": "postV1DraftsByIdSend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "daily_limit": { "type": "integer" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "hold_context": { "nullable": true, "properties": { "review_causes": { "items": { "enum": [ "content_warning", "first_contact", "send_window", "mailbox_policy" ], "type": "string" }, "nullable": true, "type": "array" }, "summary_reasons": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "trigger_source": { "enum": [ "mailbox_policy", "scanner", "both" ], "type": "string" } }, "required": [ "trigger_source", "summary_reasons" ], "type": "object" }, "html_sanitized": { "type": "boolean" }, "message_id": { "type": "string" }, "removed_categories": { "items": { "type": "string" }, "type": "array" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "sends_remaining": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "sent", "quarantined", "blocked", "pending_review" ], "type": "string" }, "warning": { "nullable": true, "type": "string" } }, "required": [ "message_id", "status", "daily_limit", "sends_remaining" ], "type": "object" } } }, "description": "Success" }, "202": { "content": { "application/json": { "schema": { "properties": { "daily_limit": { "type": "integer" }, "message_id": { "type": "string" }, "sends_remaining": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "queued_for_dispatch" ], "type": "string" } }, "required": [ "message_id", "status", "daily_limit", "sends_remaining" ], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Send a draft", "tags": [ "drafts" ] } }, "/v1/inbound-blocklist": { "get": { "operationId": "getV1InboundBlocklist", "parameters": [ { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "blocklist": { "items": { "properties": { "added_by_actor_id": { "nullable": true, "type": "string" }, "added_by_actor_type": { "nullable": true, "type": "string" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" } }, "required": [ "email", "reason", "source", "created_at" ], "type": "object" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "required": [ "blocklist" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: ACCOUNT_SUSPENDED, EMAIL_NOT_VERIFIED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List the account-wide inbound sender blocklist", "tags": [ "inbound-firewall" ] }, "post": { "operationId": "postV1InboundBlocklist", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "minLength": 1, "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "added_by_actor_id": { "nullable": true, "type": "string" }, "added_by_actor_type": { "nullable": true, "type": "string" }, "already_existed": { "type": "boolean" }, "created_at": { "nullable": true, "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" } }, "required": [ "email", "reason", "source", "created_at", "already_existed" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: ACCOUNT_SUSPENDED, EMAIL_NOT_VERIFIED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Add an inbound sender-blocklist entry", "tags": [ "inbound-firewall" ] } }, "/v1/inbound-blocklist/bulk": { "post": { "operationId": "postV1InboundBlocklistBulk", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "emails": { "items": { "maxLength": 254, "minLength": 1, "type": "string" }, "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "emails" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "added": { "items": { "properties": { "created_at": { "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" } }, "required": [ "email", "created_at" ], "type": "object" }, "type": "array" }, "already_existed": { "items": { "type": "string" }, "type": "array" }, "counts": { "properties": { "added": { "type": "integer" }, "already_existed": { "type": "integer" }, "invalid": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "added", "already_existed", "invalid", "total" ], "type": "object" }, "invalid": { "items": { "properties": { "email": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "email", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "added", "already_existed", "invalid", "counts" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: ACCOUNT_SUSPENDED, EMAIL_NOT_VERIFIED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Bulk-add inbound sender-blocklist entries", "tags": [ "inbound-firewall" ] } }, "/v1/inbound-blocklist/{email}": { "delete": { "operationId": "deleteV1InboundBlocklistByEmail", "parameters": [ { "in": "path", "name": "email", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "email" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: ACCOUNT_SUSPENDED, EMAIL_NOT_VERIFIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Remove an inbound sender-blocklist entry", "tags": [ "inbound-firewall" ] } }, "/v1/legal-holds": { "get": { "operationId": "getV1LegalHolds", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "legal_holds": { "items": { "properties": { "applied_at": { "format": "date-time", "type": "string" }, "applied_by_type": { "enum": [ "admin", "customer", "system" ], "type": "string" }, "case_reference": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mailbox_id": { "format": "uuid", "nullable": true, "type": "string" }, "reason": { "type": "string" }, "release_reason": { "nullable": true, "type": "string" }, "released_at": { "format": "date-time", "nullable": true, "type": "string" }, "released_by_type": { "anyOf": [ { "enum": [ "admin", "customer", "system" ], "type": "string" }, { "nullable": true } ] }, "scope": { "enum": [ "account", "mailbox" ], "type": "string" } }, "required": [ "id", "scope", "case_reference", "reason", "applied_at", "applied_by_type" ], "type": "object" }, "type": "array" } }, "required": [ "legal_holds" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List legal holds", "tags": [ "legal-holds" ] }, "post": { "operationId": "postV1LegalHolds", "requestBody": { "content": { "application/json": { "schema": { "properties": { "case_reference": { "maxLength": 200, "type": "string" }, "mailbox_id": { "format": "uuid", "type": "string" }, "reason": { "maxLength": 2000, "minLength": 1, "type": "string" }, "scope": { "enum": [ "account", "mailbox" ], "type": "string" } }, "required": [ "scope", "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "applied_at": { "format": "date-time", "type": "string" }, "applied_by_type": { "enum": [ "admin", "customer", "system" ], "type": "string" }, "case_reference": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mailbox_id": { "format": "uuid", "nullable": true, "type": "string" }, "reason": { "type": "string" }, "release_reason": { "nullable": true, "type": "string" }, "released_at": { "format": "date-time", "nullable": true, "type": "string" }, "released_by_type": { "anyOf": [ { "enum": [ "admin", "customer", "system" ], "type": "string" }, { "nullable": true } ] }, "scope": { "enum": [ "account", "mailbox" ], "type": "string" } }, "required": [ "id", "scope", "case_reference", "reason", "applied_at", "applied_by_type" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Create a legal hold (Pro+)", "tags": [ "legal-holds" ] } }, "/v1/legal-holds/{id}": { "get": { "operationId": "getV1LegalHoldsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "applied_at": { "format": "date-time", "type": "string" }, "applied_by_type": { "enum": [ "admin", "customer", "system" ], "type": "string" }, "case_reference": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mailbox_id": { "format": "uuid", "nullable": true, "type": "string" }, "reason": { "type": "string" }, "release_reason": { "nullable": true, "type": "string" }, "released_at": { "format": "date-time", "nullable": true, "type": "string" }, "released_by_type": { "anyOf": [ { "enum": [ "admin", "customer", "system" ], "type": "string" }, { "nullable": true } ] }, "scope": { "enum": [ "account", "mailbox" ], "type": "string" } }, "required": [ "id", "scope", "case_reference", "reason", "applied_at", "applied_by_type" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE, EMAIL_NOT_VERIFIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get a legal hold", "tags": [ "legal-holds" ] } }, "/v1/legal-holds/{id}/release": { "post": { "operationId": "postV1LegalHoldsByIdRelease", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "release_reason": { "maxLength": 2000, "minLength": 1, "type": "string" } }, "required": [ "release_reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "applied_at": { "format": "date-time", "type": "string" }, "applied_by_type": { "enum": [ "admin", "customer", "system" ], "type": "string" }, "case_reference": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mailbox_id": { "format": "uuid", "nullable": true, "type": "string" }, "reason": { "type": "string" }, "release_reason": { "nullable": true, "type": "string" }, "released_at": { "format": "date-time", "nullable": true, "type": "string" }, "released_by_type": { "anyOf": [ { "enum": [ "admin", "customer", "system" ], "type": "string" }, { "nullable": true } ] }, "scope": { "enum": [ "account", "mailbox" ], "type": "string" } }, "required": [ "id", "scope", "case_reference", "reason", "applied_at", "applied_by_type" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE, EMAIL_NOT_VERIFIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Release a legal hold", "tags": [ "legal-holds" ] } }, "/v1/mailboxes": { "get": { "operationId": "getV1Mailboxes", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "mailboxes": { "items": { "properties": { "address": { "type": "string" }, "agent_authoring_mode": { "enum": [ "send_and_draft", "draft_only", "read_only" ], "type": "string" }, "agent_send_containment": { "type": "boolean" }, "agent_send_policy": { "enum": [ "restricted", "open" ], "type": "string" }, "allow_thread_replies": { "type": "boolean" }, "attachment_access_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "attachment_access_accepted_version": { "nullable": true, "type": "string" }, "attachment_access_enabled": { "type": "boolean" }, "attachment_allowed_file_families": { "items": { "enum": [ "pdf", "text", "csv", "image", "*" ], "type": "string" }, "type": "array" }, "attachment_exposure_mode": { "enum": [ "metadata_only", "derived_content", "raw_download_selected_types" ], "type": "string" }, "attachment_image_access_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "attachment_image_access_accepted_version": { "nullable": true, "type": "string" }, "attachment_policy_version": { "nullable": true, "type": "string" }, "attachment_reauth_at": { "format": "date-time", "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "current_disclaimer_version": { "type": "string" }, "current_image_risk_version": { "type": "string" }, "default_subaddress_mode": { "enum": [ "reply_to", "from", "none" ], "type": "string" }, "hitl_mode": { "enum": [ "disabled", "all_outbound", "risky_only" ], "type": "string" }, "id": { "type": "string" }, "image_raw_download_confirmed": { "type": "boolean" }, "instruction_trust_mode": { "enum": [ "disabled", "enabled" ], "type": "string" }, "instruction_trust_strict_recipient": { "type": "boolean" }, "last_applied_policy_mode": { "nullable": true, "type": "string" }, "legacy_wildcard_active": { "type": "boolean" }, "name": { "type": "string" }, "outbound_attachments": { "additionalProperties": true, "nullable": true, "type": "object" }, "pii_mode": { "enum": [ "passthrough", "redacted" ], "type": "string" }, "pii_redaction_config": { "additionalProperties": true, "nullable": true, "type": "object" }, "recipient_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "restricted_by": { "enum": [ "mailbox_allowlist", "agent_containment", null ], "nullable": true, "type": "string" }, "scanner_policy": { "additionalProperties": true, "nullable": true, "type": "object" }, "sender_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "status": { "enum": [ "active", "paused", "deleted" ], "type": "string" } }, "required": [ "id", "name", "address", "status", "pii_mode", "attachment_exposure_mode", "attachment_allowed_file_families", "default_subaddress_mode", "recipient_policy_mode", "sender_policy_mode", "hitl_mode", "allow_thread_replies", "agent_send_containment", "agent_send_policy", "restricted_by", "pii_redaction_config", "agent_authoring_mode", "last_applied_policy_mode", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "mailboxes" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List mailboxes", "tags": [ "mailboxes" ] }, "post": { "operationId": "postV1Mailboxes", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "domain_id": { "format": "uuid", "type": "string" }, "name": { "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9][a-z0-9._-]*$", "type": "string" }, "self_hosted_imap_folder": { "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "address": { "type": "string" }, "agent_authoring_mode": { "enum": [ "send_and_draft", "draft_only", "read_only" ], "type": "string" }, "agent_send_containment": { "type": "boolean" }, "agent_send_policy": { "enum": [ "restricted", "open" ], "type": "string" }, "allow_thread_replies": { "type": "boolean" }, "hitl_mode": { "enum": [ "disabled", "all_outbound", "risky_only" ], "type": "string" }, "id": { "type": "string" }, "last_applied_policy_mode": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "recipient_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "restricted_by": { "enum": [ "mailbox_allowlist", "agent_containment", null ], "nullable": true, "type": "string" }, "sender_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" } }, "required": [ "id", "name", "address", "recipient_policy_mode", "sender_policy_mode", "hitl_mode", "allow_thread_replies", "agent_send_containment", "agent_send_policy", "restricted_by", "agent_authoring_mode", "last_applied_policy_mode" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "properties": { "code": { "type": "string" }, "conflicting_mailbox": { "additionalProperties": false, "properties": { "full_address": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name", "full_address" ], "type": "object" }, "details": { "additionalProperties": true, "type": "object" }, "error": { "type": "string" } }, "required": [ "error", "code" ], "type": "object" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Create a mailbox (admin)", "tags": [ "mailboxes" ] } }, "/v1/mailboxes/{id}": { "delete": { "operationId": "deleteV1MailboxesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "enum": [ "deleted" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Delete a mailbox (admin)", "tags": [ "mailboxes" ] }, "get": { "operationId": "getV1MailboxesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "type": "string" }, "agent_authoring_mode": { "enum": [ "send_and_draft", "draft_only", "read_only" ], "type": "string" }, "agent_send_containment": { "type": "boolean" }, "agent_send_policy": { "enum": [ "restricted", "open" ], "type": "string" }, "allow_thread_replies": { "type": "boolean" }, "attachment_access_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "attachment_access_accepted_version": { "nullable": true, "type": "string" }, "attachment_access_enabled": { "type": "boolean" }, "attachment_allowed_file_families": { "items": { "enum": [ "pdf", "text", "csv", "image", "*" ], "type": "string" }, "type": "array" }, "attachment_exposure_mode": { "enum": [ "metadata_only", "derived_content", "raw_download_selected_types" ], "type": "string" }, "attachment_image_access_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "attachment_image_access_accepted_version": { "nullable": true, "type": "string" }, "attachment_policy_version": { "nullable": true, "type": "string" }, "attachment_reauth_at": { "format": "date-time", "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "current_address_attestation_version": { "type": "string" }, "current_disclaimer_version": { "type": "string" }, "current_image_risk_version": { "type": "string" }, "current_residual_ack_version": { "type": "string" }, "default_subaddress_mode": { "enum": [ "reply_to", "from", "none" ], "type": "string" }, "hitl_mode": { "enum": [ "disabled", "all_outbound", "risky_only" ], "type": "string" }, "id": { "type": "string" }, "image_raw_download_confirmed": { "type": "boolean" }, "instruction_trust_mode": { "enum": [ "disabled", "enabled" ], "type": "string" }, "instruction_trust_strict_recipient": { "type": "boolean" }, "last_applied_policy_mode": { "nullable": true, "type": "string" }, "legacy_wildcard_active": { "type": "boolean" }, "name": { "type": "string" }, "outbound_attachments": { "additionalProperties": true, "nullable": true, "type": "object" }, "pii_mode": { "enum": [ "passthrough", "redacted" ], "type": "string" }, "pii_redaction_config": { "additionalProperties": true, "nullable": true, "type": "object" }, "recipient_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "restricted_by": { "enum": [ "mailbox_allowlist", "agent_containment", null ], "nullable": true, "type": "string" }, "scanner_policy": { "additionalProperties": true, "nullable": true, "type": "object" }, "sender_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "status": { "enum": [ "active", "paused", "deleted" ], "type": "string" } }, "required": [ "id", "name", "address", "status", "pii_mode", "attachment_exposure_mode", "attachment_allowed_file_families", "default_subaddress_mode", "recipient_policy_mode", "sender_policy_mode", "hitl_mode", "allow_thread_replies", "agent_send_containment", "agent_send_policy", "restricted_by", "pii_redaction_config", "agent_authoring_mode", "last_applied_policy_mode", "created_at" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get a mailbox", "tags": [ "mailboxes" ] }, "patch": { "operationId": "patchV1MailboxesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "agent_authoring_mode": { "enum": [ "send_and_draft", "draft_only", "read_only" ], "type": "string" }, "agent_send_containment": { "type": "boolean" }, "agent_send_policy": { "enum": [ "restricted", "open" ], "type": "string" }, "allow_thread_replies": { "type": "boolean" }, "apply_policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted" ], "type": "string" }, "approval_expiry": { "enum": [ "24h", "72h", "7d", "never" ], "type": "string" }, "confirm_open_human_sends": { "type": "boolean" }, "default_subaddress_mode": { "enum": [ "reply_to", "from", "none" ], "type": "string" }, "force_empty": { "type": "boolean" }, "hitl_mode": { "enum": [ "disabled", "all_outbound", "risky_only" ], "type": "string" }, "pii_mode": { "enum": [ "passthrough", "redacted" ], "type": "string" }, "pii_redaction_config": { "additionalProperties": { "additionalProperties": false, "properties": { "operator": { "additionalProperties": false, "properties": { "keep_last": { "maximum": 6, "minimum": 1, "type": "integer" }, "kind": { "enum": [ "replace_with_type", "partial_mask", "hash_replace" ], "type": "string" }, "mask_char": { "maxLength": 1, "minLength": 1, "type": "string" } }, "required": [ "kind" ], "type": "object" }, "redact": { "enum": [ true, false ] } }, "required": [ "redact" ], "type": "object" }, "nullable": true, "type": "object" }, "reauth_challenge": { "type": "string" }, "reauth_token": { "type": "string" }, "recipient_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "scanner_policy": { "oneOf": [ { "additionalProperties": false, "properties": { "disabled_proxy_criteria": { "items": { "enum": [ "prompt_injection", "jailbreak", "function_call_risk", "profanity", "confidentiality_leak", "unauthorized_liability", "toxicity", "hate_speech", "violence", "harassment", "self_harm", "sexual_content" ], "type": "string" }, "type": "array", "uniqueItems": true }, "disabled_scanners": { "items": { "enum": [ "prompt-injection", "attachment-policy", "mime-mismatch", "pii", "secrets", "url-reputation" ], "type": "string" }, "type": "array", "uniqueItems": true }, "language_mode": { "enum": [ "english_only", "allow_all_languages", "disabled" ], "type": "string" }, "outbound_pii_policy": { "additionalProperties": false, "properties": { "credit_card": { "enum": [ "allow", "allow_with_warning", "review", "quarantine", "block" ], "type": "string" }, "phone_number": { "enum": [ "allow", "allow_with_warning", "review", "quarantine", "block" ], "type": "string" }, "ssn": { "enum": [ "allow", "allow_with_warning", "review", "quarantine", "block" ], "type": "string" } }, "type": "object" }, "outbound_review_policy": { "additionalProperties": false, "properties": { "approval_note": { "enum": [ "optional", "required_for_sensitive_pii" ], "type": "string" } }, "type": "object" } }, "type": "object" }, { "nullable": true } ] }, "send_window": { "oneOf": [ { "additionalProperties": false, "properties": { "days": { "items": { "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "type": "string" }, "type": "array" }, "end": { "type": "string" }, "outside_action": { "enum": [ "require_approval", "block" ], "type": "string" }, "start": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "timezone", "days", "start", "end", "outside_action" ], "type": "object" }, { "nullable": true } ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "type": "string" }, "agent_authoring_mode": { "enum": [ "send_and_draft", "draft_only", "read_only" ], "type": "string" }, "agent_send_containment": { "type": "boolean" }, "agent_send_policy": { "enum": [ "restricted", "open" ], "type": "string" }, "allow_thread_replies": { "type": "boolean" }, "attachment_access_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "attachment_access_accepted_version": { "nullable": true, "type": "string" }, "attachment_access_enabled": { "type": "boolean" }, "attachment_allowed_file_families": { "items": { "enum": [ "pdf", "text", "csv", "image", "*" ], "type": "string" }, "type": "array" }, "attachment_exposure_mode": { "enum": [ "metadata_only", "derived_content", "raw_download_selected_types" ], "type": "string" }, "attachment_image_access_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "attachment_image_access_accepted_version": { "nullable": true, "type": "string" }, "attachment_policy_version": { "nullable": true, "type": "string" }, "attachment_reauth_at": { "format": "date-time", "nullable": true, "type": "string" }, "current_disclaimer_version": { "type": "string" }, "current_image_risk_version": { "type": "string" }, "default_subaddress_mode": { "enum": [ "reply_to", "from", "none" ], "type": "string" }, "hitl_mode": { "enum": [ "disabled", "all_outbound", "risky_only" ], "type": "string" }, "id": { "type": "string" }, "image_raw_download_confirmed": { "type": "boolean" }, "last_applied_policy_mode": { "nullable": true, "type": "string" }, "legacy_wildcard_active": { "type": "boolean" }, "name": { "type": "string" }, "pii_mode": { "enum": [ "passthrough", "redacted" ], "type": "string" }, "pii_redaction_config": { "additionalProperties": true, "nullable": true, "type": "object" }, "recipient_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "restricted_by": { "enum": [ "mailbox_allowlist", "agent_containment", null ], "nullable": true, "type": "string" }, "scanner_policy": { "additionalProperties": true, "nullable": true, "type": "object" }, "send_window": { "additionalProperties": true, "nullable": true, "type": "object" }, "sender_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" } }, "required": [ "id", "name", "address", "pii_mode", "attachment_access_enabled", "attachment_access_accepted_at", "attachment_access_accepted_version", "attachment_exposure_mode", "attachment_allowed_file_families", "attachment_reauth_at", "attachment_policy_version", "image_raw_download_confirmed", "current_image_risk_version", "attachment_image_access_accepted_at", "attachment_image_access_accepted_version", "current_disclaimer_version", "legacy_wildcard_active", "default_subaddress_mode", "recipient_policy_mode", "sender_policy_mode", "hitl_mode", "allow_thread_replies", "agent_send_containment", "agent_send_policy", "restricted_by", "pii_redaction_config", "agent_authoring_mode", "send_window", "last_applied_policy_mode" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Update a mailbox", "tags": [ "mailboxes" ] } }, "/v1/mailboxes/{id}/attachment-access": { "post": { "operationId": "postV1MailboxesByIdAttachmentAccess", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "additionalProperties": false, "properties": { "accept_disclaimer_version": { "minLength": 1, "type": "string" }, "enable": { "type": "boolean" } }, "required": [ "enable" ], "type": "object" }, { "additionalProperties": false, "properties": { "accept_disclaimer_version": { "minLength": 1, "type": "string" }, "accept_image_risk_version": { "minLength": 1, "type": "string" }, "allowed_file_families": { "items": { "minLength": 1, "type": "string" }, "type": "array", "uniqueItems": true }, "mode": { "enum": [ "metadata_only", "derived_content", "raw_download_selected_types" ], "type": "string" }, "reauth_challenge": { "minLength": 1, "type": "string" }, "reauth_token": { "minLength": 1, "type": "string" } }, "required": [ "mode" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "accepted_version": { "nullable": true, "type": "string" }, "allowed_file_families": { "items": { "enum": [ "pdf", "text", "csv", "image", "*" ], "type": "string" }, "type": "array" }, "attachment_access_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "attachment_access_accepted_version": { "nullable": true, "type": "string" }, "attachment_access_enabled": { "type": "boolean" }, "attachment_image_access_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "attachment_image_access_accepted_version": { "nullable": true, "type": "string" }, "current_disclaimer_version": { "type": "string" }, "current_image_risk_version": { "type": "string" }, "image_raw_download_confirmed": { "type": "boolean" }, "legacy_wildcard_active": { "type": "boolean" }, "mailbox_id": { "type": "string" }, "mode": { "enum": [ "metadata_only", "derived_content", "raw_download_selected_types" ], "type": "string" } }, "required": [ "mailbox_id", "mode", "allowed_file_families", "accepted_at", "accepted_version", "attachment_access_enabled", "attachment_access_accepted_at", "attachment_access_accepted_version", "image_raw_download_confirmed", "current_image_risk_version", "attachment_image_access_accepted_at", "attachment_image_access_accepted_version", "current_disclaimer_version", "legacy_wildcard_active" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Configure attachment access (session re-auth)", "tags": [ "mailboxes" ] } }, "/v1/mailboxes/{id}/drafts": { "get": { "operationId": "getV1MailboxesByIdDrafts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "before", "required": false, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "drafts": { "items": { "properties": { "compose_held_at": { "format": "date-time", "nullable": true, "type": "string" }, "compose_held_decision": { "enum": [ "quarantine", "block", "require_human_approval", null ], "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "last_dispatch_attempt_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_dispatch_error_code": { "nullable": true, "type": "string" }, "mailbox_id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "original_send_at": { "format": "date-time", "nullable": true, "type": "string" }, "recipient": { "type": "string" }, "releasable": { "type": "boolean" }, "send_at": { "format": "date-time", "nullable": true, "type": "string" }, "send_attempts": { "type": "integer" }, "sender": { "type": "string" }, "state": { "enum": [ "draft" ], "type": "string" }, "subaddress_instance_id": { "nullable": true, "type": "string" }, "subject": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "worst_decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "id", "mailbox_id", "state", "sender", "recipient", "subject", "worst_decision", "send_attempts", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" } }, "required": [ "drafts", "has_more" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: MAILBOX_ACCESS_DENIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List a mailbox's drafts", "tags": [ "drafts" ] } }, "/v1/mailboxes/{id}/messages": { "get": { "operationId": "getV1MailboxesByIdMessages", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "compose_held", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "inbound", "outbound" ], "type": "string" } }, { "in": "query", "name": "has_attachment", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "include_firewall_blocked", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "in": "query", "name": "search", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "in": "query", "name": "sender", "required": false, "schema": { "maxLength": 254, "type": "string" } }, { "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "starred", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "unread", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "until", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "view", "required": false, "schema": { "enum": [ "summary", "verbose" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "messages": { "items": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "body_preview": { "maxLength": 200, "nullable": true, "type": "string" }, "compose_held_at": { "format": "date-time", "nullable": true, "type": "string" }, "compose_held_decision": { "enum": [ "quarantine", "block", "require_human_approval", null ], "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "dashboard_url": { "nullable": true, "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "type": "string" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "firewall_block": { "additionalProperties": false, "nullable": true, "properties": { "envelope_sender": { "nullable": true, "type": "string" }, "from_address": { "nullable": true, "type": "string" }, "matched_field": { "enum": [ "envelope", "from", null ], "nullable": true, "type": "string" }, "matched_list": { "enum": [ "account_blocklist", "mailbox_allowlist", null ], "nullable": true, "type": "string" }, "matched_pattern": { "nullable": true, "type": "string" }, "mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "reason_code": { "enum": [ "SENDER_BLOCKED", "SENDER_NOT_ON_ALLOWLIST" ], "type": "string" } }, "required": [ "reason_code", "mode" ], "type": "object" }, "has_attachment": { "type": "boolean" }, "id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "read_at": { "nullable": true, "type": "string" }, "recipient": { "type": "string" }, "releasable": { "type": "boolean" }, "review_expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "review_trigger_source": { "enum": [ "mailbox_policy", "scanner", "both", null ], "nullable": true, "type": "string" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "sender": { "type": "string" }, "sender_authentication": { "additionalProperties": false, "nullable": true, "properties": { "verdict": { "enum": [ "verified_aligned", "authenticated_unaligned", "failed", "none", "error", null ], "nullable": true, "type": "string" } }, "required": [ "verdict" ], "type": "object" }, "starred": { "type": "boolean" }, "state": { "type": "string" }, "subaddress_instance_id": { "nullable": true, "type": "string" }, "subject": { "type": "string" }, "thread_id": { "nullable": true, "type": "string" } }, "required": [ "id", "direction", "state", "sender", "recipient", "subject", "created_at", "body_preview" ], "type": "object" }, "type": "array" } }, "required": [ "messages" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: MAILBOX_ACCESS_DENIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List a mailbox's messages", "tags": [ "messages" ] } }, "/v1/mailboxes/{id}/messages/wait": { "get": { "operationId": "getV1MailboxesByIdMessagesWait", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "timeout", "required": false, "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "oneOf": [ { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "body_preview": { "maxLength": 200, "nullable": true, "type": "string" }, "compose_held_at": { "format": "date-time", "nullable": true, "type": "string" }, "compose_held_decision": { "enum": [ "quarantine", "block", "require_human_approval", null ], "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "dashboard_url": { "nullable": true, "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "type": "string" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "firewall_block": { "additionalProperties": false, "nullable": true, "properties": { "envelope_sender": { "nullable": true, "type": "string" }, "from_address": { "nullable": true, "type": "string" }, "matched_field": { "enum": [ "envelope", "from", null ], "nullable": true, "type": "string" }, "matched_list": { "enum": [ "account_blocklist", "mailbox_allowlist", null ], "nullable": true, "type": "string" }, "matched_pattern": { "nullable": true, "type": "string" }, "mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "reason_code": { "enum": [ "SENDER_BLOCKED", "SENDER_NOT_ON_ALLOWLIST" ], "type": "string" } }, "required": [ "reason_code", "mode" ], "type": "object" }, "has_attachment": { "type": "boolean" }, "id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "read_at": { "nullable": true, "type": "string" }, "recipient": { "type": "string" }, "releasable": { "type": "boolean" }, "review_expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "review_trigger_source": { "enum": [ "mailbox_policy", "scanner", "both", null ], "nullable": true, "type": "string" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "sender": { "type": "string" }, "sender_authentication": { "additionalProperties": false, "nullable": true, "properties": { "verdict": { "enum": [ "verified_aligned", "authenticated_unaligned", "failed", "none", "error", null ], "nullable": true, "type": "string" } }, "required": [ "verdict" ], "type": "object" }, "starred": { "type": "boolean" }, "state": { "type": "string" }, "subaddress_instance_id": { "nullable": true, "type": "string" }, "subject": { "type": "string" }, "thread_id": { "nullable": true, "type": "string" } }, "required": [ "id", "direction", "state", "sender", "recipient", "subject", "created_at", "body_preview" ], "type": "object" }, { "nullable": true } ] } }, "required": [ "message" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: MAILBOX_ACCESS_DENIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Long-poll for the next message", "tags": [ "messages" ] } }, "/v1/mailboxes/{id}/outbound-attachments": { "post": { "operationId": "postV1MailboxesByIdOutboundAttachments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accept_disclaimer_version": { "minLength": 1, "type": "string" }, "accept_image_risk_version": { "minLength": 1, "type": "string" }, "enabled": { "type": "boolean" }, "reauth_challenge": { "minLength": 1, "type": "string" }, "reauth_token": { "minLength": 1, "type": "string" } }, "required": [ "enabled" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "accepted_version": { "nullable": true, "type": "string" }, "current_disclaimer_version": { "type": "string" }, "current_image_risk_version": { "type": "string" }, "enabled": { "type": "boolean" }, "image_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "image_accepted_version": { "nullable": true, "type": "string" }, "mailbox_id": { "type": "string" }, "reauth_at": { "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "mailbox_id", "enabled", "accepted_at", "accepted_version", "reauth_at", "image_accepted_at", "image_accepted_version", "current_disclaimer_version", "current_image_risk_version" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Configure outbound attachments (session re-auth)", "tags": [ "mailboxes" ] } }, "/v1/mailboxes/{id}/policy": { "get": { "operationId": "getV1MailboxesByIdPolicy", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_authoring_mode": { "enum": [ "send_and_draft", "draft_only", "read_only" ], "type": "string" }, "agent_send_policy": { "enum": [ "restricted", "open" ], "type": "string" }, "allow_thread_replies": { "type": "boolean" }, "approval_expiry": { "enum": [ "24h", "72h", "7d", "never" ], "type": "string" }, "binding": { "properties": { "permitted_verbs": { "items": { "enum": [ "send", "reply", "draft_create", "draft_update", "draft_send" ], "type": "string" }, "type": "array" }, "scope": { "enum": [ "admin", "agent" ], "type": "string" } }, "required": [ "scope", "permitted_verbs" ], "type": "object" }, "enforcement": { "properties": { "risky_only": { "enum": [ "off", "shadow", "enforce" ], "type": "string" }, "send_window": { "enum": [ "off", "shadow", "enforce" ], "type": "string" } }, "required": [ "risky_only", "send_window" ], "type": "object" }, "hitl_mode": { "enum": [ "disabled", "all_outbound", "risky_only" ], "type": "string" }, "last_applied_policy_mode": { "nullable": true, "type": "string" }, "latest_revision_id": { "nullable": true, "type": "string" }, "mailbox_id": { "type": "string" }, "policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted", "custom" ], "type": "string" }, "recipient_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "restricted_by": { "enum": [ "mailbox_allowlist", "agent_containment", null ], "nullable": true, "type": "string" }, "send_window": { "additionalProperties": true, "nullable": true, "type": "object" } }, "required": [ "mailbox_id", "policy_mode", "enforcement", "last_applied_policy_mode", "agent_authoring_mode", "agent_send_policy", "restricted_by", "hitl_mode", "approval_expiry", "send_window", "allow_thread_replies", "recipient_policy_mode", "latest_revision_id", "binding" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Read a mailbox's effective policy (derived mode, enforcement state, what binds this key)", "tags": [ "policy" ] } }, "/v1/mailboxes/{id}/policy/preview": { "post": { "operationId": "postV1MailboxesByIdPolicyPreview", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at_time": { "format": "date-time", "type": "string" }, "body": { "maxLength": 100000, "type": "string" }, "run_content_scan": { "type": "boolean" }, "subject": { "maxLength": 2000, "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "to" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "budget": { "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "warmup_applied": { "type": "boolean" } }, "required": [ "limit", "remaining", "warmup_applied" ], "type": "object" }, "content_scan_run": { "type": "boolean" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "mailbox_id": { "type": "string" }, "result": { "enum": [ "passes_all_checks_run", "would_hold", "would_block" ], "type": "string" }, "result_summary": { "type": "string" }, "trace": { "items": { "properties": { "details": { "additionalProperties": true, "type": "object" }, "gate": { "enum": [ "authoring", "recipient_authority", "send_window", "content_scan", "human_review", "send_budget" ], "type": "string" }, "outcome": { "enum": [ "pass", "would_hold", "would_block", "not_run", "skipped" ], "type": "string" }, "reason": { "type": "string" } }, "required": [ "gate", "outcome", "reason", "details" ], "type": "object" }, "type": "array" } }, "required": [ "mailbox_id", "result", "result_summary", "content_scan_run", "email_effect", "trace", "budget" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Dry-run a sample send against the mailbox's policy (no side effects)", "tags": [ "policy" ] } }, "/v1/mailboxes/{id}/policy/revisions": { "get": { "operationId": "getV1MailboxesByIdPolicyRevisions", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "next_cursor": { "nullable": true, "type": "string" }, "revisions": { "items": { "properties": { "actor_id": { "nullable": true, "type": "string" }, "actor_type": { "nullable": true, "type": "string" }, "containment_lever": { "enum": [ "off", "shadow", "enforce", null ], "nullable": true, "type": "string" }, "correction_of": { "nullable": true, "type": "string" }, "created_at": { "type": "string" }, "derived_mode": { "nullable": true, "type": "string" }, "diff": { "additionalProperties": true, "type": "object" }, "id": { "type": "string" }, "kind": { "enum": [ "policy_change", "system_correction" ], "type": "string" }, "legacy_derivation": { "type": "boolean" }, "reauth_used": { "nullable": true, "type": "boolean" } }, "required": [ "id", "created_at", "actor_type", "actor_id", "reauth_used", "derived_mode", "kind", "legacy_derivation", "diff" ], "type": "object" }, "type": "array" } }, "required": [ "revisions", "next_cursor" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Paginated policy revision history with before/after diffs", "tags": [ "policy" ] } }, "/v1/mailboxes/{id}/threads": { "get": { "operationId": "getV1MailboxesByIdThreads", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "before_ts", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "body_format", "required": false, "schema": { "enum": [ "text", "html" ], "type": "string" } }, { "in": "query", "name": "body_page", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "has_inbound", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "include_firewall_blocked", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "in": "query", "name": "since_ts", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "starred", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "view", "required": false, "schema": { "enum": [ "summary", "verbose" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "threads": { "items": { "properties": { "body_preview": { "nullable": true, "type": "string" }, "first_message_at": { "format": "date-time", "type": "string" }, "has_attachment": { "type": "boolean" }, "id": { "type": "string" }, "last_message_at": { "format": "date-time", "type": "string" }, "message_count": { "type": "integer" }, "participants": { "items": { "type": "string" }, "type": "array" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "starred": { "type": "boolean" }, "subject": { "type": "string" }, "unread_count": { "type": "integer" } }, "required": [ "id", "subject", "first_message_at", "last_message_at", "message_count", "unread_count", "starred", "participants" ], "type": "object" }, "type": "array" } }, "required": [ "threads" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: MAILBOX_ACCESS_DENIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List a mailbox's threads", "tags": [ "threads" ] } }, "/v1/mailboxes/{id}/threads/{thread_id}/read": { "post": { "operationId": "postV1MailboxesByIdThreadsByThreadIdRead", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "path", "name": "thread_id", "required": true, "schema": { "maxLength": 512, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "marked_count": { "minimum": 0, "type": "integer" }, "thread_id": { "type": "string" } }, "required": [ "thread_id", "marked_count" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Mark a thread read", "tags": [ "threads" ] } }, "/v1/mailboxes/{id}/threads/{thread_id}/star": { "patch": { "operationId": "patchV1MailboxesByIdThreadsByThreadIdStar", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "path", "name": "thread_id", "required": true, "schema": { "maxLength": 512, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "starred": { "type": "boolean" } }, "required": [ "starred" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "starred": { "type": "boolean" }, "thread_id": { "type": "string" }, "updated_count": { "minimum": 0, "type": "integer" } }, "required": [ "thread_id", "starred", "updated_count" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Star or unstar a thread", "tags": [ "threads" ] } }, "/v1/mailboxes/{mailboxId}/allowlist": { "get": { "operationId": "getV1MailboxesByMailboxIdAllowlist", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "allowlist": { "items": { "properties": { "added_by_actor_id": { "nullable": true, "type": "string" }, "added_by_actor_type": { "nullable": true, "type": "string" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "mailbox_id": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" } }, "required": [ "email", "mailbox_id", "created_at" ], "type": "object" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "required": [ "allowlist" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List a mailbox's recipient allowlist", "tags": [ "recipient-allowlist" ] }, "post": { "operationId": "postV1MailboxesByMailboxIdAllowlist", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "minLength": 1, "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "added_by_actor_id": { "nullable": true, "type": "string" }, "added_by_actor_type": { "nullable": true, "type": "string" }, "already_existed": { "type": "boolean" }, "created_at": { "nullable": true, "type": "string" }, "email": { "type": "string" }, "mailbox_id": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" } }, "required": [ "email", "mailbox_id", "created_at", "already_existed" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Add a recipient-allowlist entry", "tags": [ "recipient-allowlist" ] } }, "/v1/mailboxes/{mailboxId}/allowlist/blocked-attempts": { "get": { "operationId": "getV1MailboxesByMailboxIdAllowlistBlockedAttempts", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "aggregate", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "within_days", "required": false, "schema": { "maximum": 365, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "attempts": { "items": { "properties": { "actor_id": { "type": "string" }, "actor_type": { "type": "string" }, "count": { "type": "integer" }, "first_attempted_at": { "type": "string" }, "last_attempted_at": { "type": "string" }, "origins": { "items": { "type": "string" }, "type": "array" }, "recipient": { "type": "string" } }, "required": [ "recipient", "actor_type", "actor_id", "count", "first_attempted_at", "last_attempted_at", "origins" ], "type": "object" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "required": [ "attempts", "next_cursor" ], "type": "object" }, { "properties": { "attempts": { "items": { "properties": { "actor_id": { "type": "string" }, "actor_type": { "type": "string" }, "attempted_at": { "type": "string" }, "draft_id": { "nullable": true, "type": "string" }, "origin": { "type": "string" }, "recipient": { "type": "string" } }, "required": [ "attempted_at", "recipient", "actor_type", "actor_id", "origin", "draft_id" ], "type": "object" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "required": [ "attempts", "next_cursor" ], "type": "object" } ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List recipient-allowlist blocked send attempts", "tags": [ "recipient-allowlist" ] } }, "/v1/mailboxes/{mailboxId}/allowlist/bulk": { "post": { "operationId": "postV1MailboxesByMailboxIdAllowlistBulk", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "emails": { "items": { "maxLength": 254, "minLength": 1, "type": "string" }, "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "emails" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "added": { "items": { "properties": { "created_at": { "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" } }, "required": [ "email", "created_at" ], "type": "object" }, "type": "array" }, "already_existed": { "items": { "type": "string" }, "type": "array" }, "counts": { "properties": { "added": { "type": "integer" }, "already_existed": { "type": "integer" }, "invalid": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "added", "already_existed", "invalid", "total" ], "type": "object" }, "invalid": { "items": { "properties": { "email": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "email", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "added", "already_existed", "invalid", "counts" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Bulk-add recipient-allowlist entries", "tags": [ "recipient-allowlist" ] } }, "/v1/mailboxes/{mailboxId}/allowlist/{email}": { "delete": { "operationId": "deleteV1MailboxesByMailboxIdAllowlistByEmail", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "path", "name": "email", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "force_empty", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "type": "string" }, "email": { "type": "string" }, "mailbox_id": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "email", "mailbox_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Remove a recipient-allowlist entry", "tags": [ "recipient-allowlist" ] } }, "/v1/mailboxes/{mailboxId}/inbound-allowlist": { "get": { "operationId": "getV1MailboxesByMailboxIdInboundAllowlist", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "allowlist": { "items": { "properties": { "added_by_actor_id": { "nullable": true, "type": "string" }, "added_by_actor_type": { "nullable": true, "type": "string" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "mailbox_id": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" } }, "required": [ "email", "mailbox_id", "created_at" ], "type": "object" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "required": [ "allowlist" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List a mailbox's inbound sender allowlist", "tags": [ "inbound-firewall" ] }, "post": { "operationId": "postV1MailboxesByMailboxIdInboundAllowlist", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "minLength": 1, "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "added_by_actor_id": { "nullable": true, "type": "string" }, "added_by_actor_type": { "nullable": true, "type": "string" }, "already_existed": { "type": "boolean" }, "created_at": { "nullable": true, "type": "string" }, "email": { "type": "string" }, "mailbox_id": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" } }, "required": [ "email", "mailbox_id", "created_at", "already_existed" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Add an inbound sender-allowlist entry", "tags": [ "inbound-firewall" ] } }, "/v1/mailboxes/{mailboxId}/inbound-allowlist/blocked-attempts": { "get": { "operationId": "getV1MailboxesByMailboxIdInboundAllowlistBlockedAttempts", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "aggregate", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "within_days", "required": false, "schema": { "maximum": 365, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "attempts": { "items": { "properties": { "count": { "type": "integer" }, "first_attempted_at": { "type": "string" }, "last_attempted_at": { "type": "string" }, "matched_field": { "enum": [ "envelope", "from", null ], "nullable": true, "type": "string" }, "mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "reason_code": { "enum": [ "SENDER_BLOCKED", "SENDER_NOT_ON_ALLOWLIST" ], "type": "string" }, "sender": { "type": "string" } }, "required": [ "sender", "mode", "reason_code", "count", "first_attempted_at", "last_attempted_at" ], "type": "object" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "required": [ "attempts", "next_cursor" ], "type": "object" }, { "properties": { "attempts": { "items": { "properties": { "attempted_at": { "type": "string" }, "envelope_sender": { "nullable": true, "type": "string" }, "from_address": { "nullable": true, "type": "string" }, "matched_field": { "enum": [ "envelope", "from", null ], "nullable": true, "type": "string" }, "matched_list": { "enum": [ "account_blocklist", "mailbox_allowlist", null ], "nullable": true, "type": "string" }, "matched_pattern": { "nullable": true, "type": "string" }, "message_id": { "nullable": true, "type": "string" }, "mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "reason_code": { "enum": [ "SENDER_BLOCKED", "SENDER_NOT_ON_ALLOWLIST" ], "type": "string" } }, "required": [ "attempted_at", "reason_code", "mode" ], "type": "object" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "required": [ "attempts", "next_cursor" ], "type": "object" } ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List inbound-firewall blocked attempts", "tags": [ "inbound-firewall" ] } }, "/v1/mailboxes/{mailboxId}/inbound-allowlist/bulk": { "post": { "operationId": "postV1MailboxesByMailboxIdInboundAllowlistBulk", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "emails": { "items": { "maxLength": 254, "minLength": 1, "type": "string" }, "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "emails" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "added": { "items": { "properties": { "created_at": { "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" } }, "required": [ "email", "created_at" ], "type": "object" }, "type": "array" }, "already_existed": { "items": { "type": "string" }, "type": "array" }, "counts": { "properties": { "added": { "type": "integer" }, "already_existed": { "type": "integer" }, "invalid": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "added", "already_existed", "invalid", "total" ], "type": "object" }, "invalid": { "items": { "properties": { "email": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "email", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "added", "already_existed", "invalid", "counts" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Bulk-add inbound sender-allowlist entries", "tags": [ "inbound-firewall" ] } }, "/v1/mailboxes/{mailboxId}/inbound-allowlist/{email}": { "delete": { "operationId": "deleteV1MailboxesByMailboxIdInboundAllowlistByEmail", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "path", "name": "email", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "force_empty", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "type": "string" }, "email": { "type": "string" }, "mailbox_id": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "email", "mailbox_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Remove an inbound sender-allowlist entry", "tags": [ "inbound-firewall" ] } }, "/v1/mailboxes/{mailboxId}/sender-policy": { "patch": { "operationId": "patchV1MailboxesByMailboxIdSenderPolicy", "parameters": [ { "in": "path", "name": "mailboxId", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "force_empty": { "type": "boolean" }, "mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" } }, "required": [ "mode" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "changed_at": { "type": "string" }, "mailbox_id": { "type": "string" }, "previous_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "sender_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" } }, "required": [ "mailbox_id", "sender_policy_mode", "previous_mode", "changed_at" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Update a mailbox's inbound sender-policy mode", "tags": [ "inbound-firewall" ] } }, "/v1/messages/idempotency": { "get": { "operationId": "getV1MessagesIdempotency", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "daily_limit": { "type": "integer" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "hold_context": { "nullable": true, "properties": { "review_causes": { "items": { "enum": [ "content_warning", "first_contact", "send_window", "mailbox_policy" ], "type": "string" }, "nullable": true, "type": "array" }, "summary_reasons": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "trigger_source": { "enum": [ "mailbox_policy", "scanner", "both" ], "type": "string" } }, "required": [ "trigger_source", "summary_reasons" ], "type": "object" }, "html_sanitized": { "type": "boolean" }, "message_id": { "type": "string" }, "removed_categories": { "items": { "type": "string" }, "type": "array" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "sends_remaining": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "sent", "quarantined", "blocked", "pending_review" ], "type": "string" }, "warning": { "nullable": true, "type": "string" } }, "required": [ "message_id", "status", "daily_limit", "sends_remaining" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Look up a message by idempotency key", "tags": [ "messages" ] } }, "/v1/messages/send": { "post": { "operationId": "postV1MessagesSend", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachment_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array", "uniqueItems": true }, "body": { "type": "string" }, "from_mailbox": { "minLength": 1, "type": "string" }, "html": { "maxLength": 1000000, "type": "string" }, "subaddress_instance_id": { "maxLength": 128, "minLength": 1, "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$", "type": "string" }, "subaddress_mode": { "enum": [ "reply_to", "from", "none" ], "type": "string" }, "subject": { "maxLength": 998, "pattern": "^[^\\r\\n]*$", "type": "string" }, "thread_id": { "minLength": 1, "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "body" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "daily_limit": { "type": "integer" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "hold_context": { "nullable": true, "properties": { "review_causes": { "items": { "enum": [ "content_warning", "first_contact", "send_window", "mailbox_policy" ], "type": "string" }, "nullable": true, "type": "array" }, "summary_reasons": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "trigger_source": { "enum": [ "mailbox_policy", "scanner", "both" ], "type": "string" } }, "required": [ "trigger_source", "summary_reasons" ], "type": "object" }, "html_sanitized": { "type": "boolean" }, "message_id": { "type": "string" }, "removed_categories": { "items": { "type": "string" }, "type": "array" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "sends_remaining": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "sent", "quarantined", "blocked", "pending_review" ], "type": "string" }, "warning": { "nullable": true, "type": "string" } }, "required": [ "message_id", "status", "daily_limit", "sends_remaining" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Send a message", "tags": [ "messages" ] } }, "/v1/messages/{id}": { "delete": { "operationId": "deleteV1MessagesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "derivatives_tombstoned": { "type": "integer" }, "message_id": { "type": "string" }, "r2_objects_failed": { "items": { "type": "string" }, "type": "array" }, "raw_mime_deleted": { "type": "boolean" }, "status": { "enum": [ "deleted" ], "type": "string" } }, "required": [ "status", "message_id", "raw_mime_deleted", "derivatives_tombstoned", "r2_objects_failed" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Delete a message", "tags": [ "messages" ] }, "get": { "operationId": "getV1MessagesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "in": "query", "name": "body_format", "required": false, "schema": { "enum": [ "text", "html" ], "type": "string" } }, { "in": "query", "name": "body_page", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "view", "required": false, "schema": { "enum": [ "summary", "verbose" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "attachments": { "items": { "properties": { "av_scanned_at": { "type": "string" }, "av_signature": { "type": "string" }, "av_verdict": { "enum": [ "clean", "infected", "error", "skipped" ], "type": "string" }, "content_disposition": { "type": "string" }, "content_id": { "type": "string" }, "content_type": { "type": "string" }, "declared_mime_type": { "type": "string" }, "filename": { "type": "string" }, "hash": { "type": "string" }, "inline": { "type": "boolean" }, "mime_mismatch": { "type": "boolean" }, "policy_action": { "enum": [ "deliver", "metadata_only", "quarantine", "block" ], "type": "string" }, "preview_char_count": { "nullable": true, "type": "integer" }, "preview_generated_at": { "format": "date-time", "nullable": true, "type": "string" }, "preview_kind": { "enum": [ "text", null ], "nullable": true, "type": "string" }, "preview_page_count": { "nullable": true, "type": "integer" }, "preview_reason_code": { "nullable": true, "type": "string" }, "preview_status": { "enum": [ "pending", "ready", "blocked", "failed", null ], "nullable": true, "type": "string" }, "preview_truncated": { "nullable": true, "type": "boolean" }, "raw_deleted_at": { "format": "date-time", "type": "string" }, "raw_retention": { "enum": [ "not_retained", "temporary_processing", "retained_for_raw_download" ], "type": "string" }, "raw_retention_reason": { "type": "string" }, "size": { "type": "integer" }, "sniffed_mime_type": { "type": "string" }, "stored": { "type": "boolean" } }, "required": [ "filename", "content_type", "size", "hash", "policy_action" ], "type": "object" }, "type": "array" }, "body": { "properties": { "char_count": { "type": "integer" }, "content": { "nullable": true, "type": "string" }, "format": { "enum": [ "text", "html" ], "type": "string" }, "returned_char_count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "format", "content", "char_count", "returned_char_count", "truncated" ], "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "dashboard_url": { "nullable": true, "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "type": "string" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "firewall_block": { "additionalProperties": false, "nullable": true, "properties": { "envelope_sender": { "nullable": true, "type": "string" }, "from_address": { "nullable": true, "type": "string" }, "matched_field": { "enum": [ "envelope", "from", null ], "nullable": true, "type": "string" }, "matched_list": { "enum": [ "account_blocklist", "mailbox_allowlist", null ], "nullable": true, "type": "string" }, "matched_pattern": { "nullable": true, "type": "string" }, "mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "reason_code": { "enum": [ "SENDER_BLOCKED", "SENDER_NOT_ON_ALLOWLIST" ], "type": "string" } }, "required": [ "reason_code", "mode" ], "type": "object" }, "hold_context": { "nullable": true, "properties": { "review_causes": { "items": { "enum": [ "content_warning", "first_contact", "send_window", "mailbox_policy" ], "type": "string" }, "nullable": true, "type": "array" }, "summary_reasons": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "trigger_source": { "enum": [ "mailbox_policy", "scanner", "both" ], "type": "string" } }, "required": [ "trigger_source", "summary_reasons" ], "type": "object" }, "id": { "type": "string" }, "in_reply_to": { "nullable": true, "type": "string" }, "mailbox_id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "read_at": { "nullable": true, "type": "string" }, "recipient": { "type": "string" }, "review_expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "review_outcome": { "enum": [ "approved", "denied", "expired", null ], "nullable": true, "type": "string" }, "review_reason": { "nullable": true, "type": "string" }, "review_trigger_source": { "enum": [ "mailbox_policy", "scanner", "both", null ], "nullable": true, "type": "string" }, "reviewed_at": { "nullable": true, "type": "string" }, "reviewed_by_id": { "nullable": true, "type": "string" }, "reviewed_by_type": { "nullable": true, "type": "string" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "sender": { "type": "string" }, "sender_authentication": { "additionalProperties": false, "nullable": true, "properties": { "from_domain": { "nullable": true, "type": "string" }, "provenance": { "enum": [ "managed", "self_hosted_imap", null ], "nullable": true, "type": "string" }, "signing_domain": { "nullable": true, "type": "string" }, "verdict": { "enum": [ "verified_aligned", "authenticated_unaligned", "failed", "none", "error", null ], "nullable": true, "type": "string" } }, "required": [ "verdict", "provenance" ], "type": "object" }, "starred": { "type": "boolean" }, "state": { "type": "string" }, "subaddress_instance_id": { "nullable": true, "type": "string" }, "subject": { "type": "string" }, "thread_id": { "nullable": true, "type": "string" } }, "required": [ "id", "direction", "state", "sender", "recipient", "subject", "body", "created_at" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get a message", "tags": [ "messages" ] } }, "/v1/messages/{id}/approve": { "post": { "operationId": "postV1MessagesByIdApprove", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "add_to_allowlist": { "type": "boolean" }, "reason": { "maxLength": 500, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message_id": { "type": "string" }, "status": { "enum": [ "sent", "blocked" ], "type": "string" } }, "required": [ "status", "message_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Upstream failure" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Approve a held message (not agent-callable)", "tags": [ "messages" ] } }, "/v1/messages/{id}/attachments/{idx}": { "get": { "operationId": "getV1MessagesByIdAttachmentsByIdx", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "in": "path", "name": "idx", "required": true, "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "av_verdict": { "nullable": true, "type": "string" }, "content_type": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "url": { "type": "string" } }, "required": [ "url", "expires_at", "content_type", "filename", "size" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get inbound attachment metadata", "tags": [ "attachments" ] } }, "/v1/messages/{id}/attachments/{idx}/preview": { "get": { "operationId": "getV1MessagesByIdAttachmentsByIdxPreview", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "in": "path", "name": "idx", "required": true, "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachment": { "additionalProperties": false, "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "hash": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "filename", "content_type", "size", "hash" ], "type": "object" }, "preview": { "additionalProperties": false, "properties": { "char_count": { "nullable": true, "type": "integer" }, "content": { "maxLength": 20000, "type": "string" }, "extractor": { "type": "string" }, "generated_at": { "format": "date-time", "type": "string" }, "kind": { "enum": [ "text" ], "type": "string" }, "page_count": { "nullable": true, "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "kind", "content", "truncated", "char_count", "page_count", "extractor", "generated_at" ], "type": "object" } }, "required": [ "attachment", "preview" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error" } }, "summary": "Get a derived attachment preview", "tags": [ "attachments" ] } }, "/v1/messages/{id}/block": { "post": { "operationId": "postV1MessagesByIdBlock", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message_id": { "type": "string" }, "status": { "enum": [ "blocked" ], "type": "string" } }, "required": [ "status", "message_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: MAILBOX_ACCESS_DENIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Block an inbound sender for a message", "tags": [ "messages" ] } }, "/v1/messages/{id}/deny": { "post": { "operationId": "postV1MessagesByIdDeny", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "add_to_allowlist": { "type": "boolean" }, "reason": { "maxLength": 500, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message_id": { "type": "string" }, "status": { "enum": [ "denied" ], "type": "string" } }, "required": [ "status", "message_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Deny a held message (not agent-callable)", "tags": [ "messages" ] } }, "/v1/messages/{id}/firewall-release": { "post": { "operationId": "postV1MessagesByIdFirewallRelease", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "message_id": { "type": "string" }, "state": { "enum": [ "scanning" ], "type": "string" } }, "required": [ "message_id", "state" ], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Release a firewall-blocked message", "tags": [ "messages" ] } }, "/v1/messages/{id}/read": { "post": { "operationId": "postV1MessagesByIdRead", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message_id": { "type": "string" }, "read_at": { "nullable": true, "type": "string" } }, "required": [ "message_id", "read_at" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Mark a message read", "tags": [ "messages" ] } }, "/v1/messages/{id}/release": { "post": { "operationId": "postV1MessagesByIdRelease", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message_id": { "type": "string" }, "status": { "enum": [ "released", "sent", "blocked" ], "type": "string" } }, "required": [ "status", "message_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Upstream failure" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Release a quarantined message", "tags": [ "messages" ] } }, "/v1/messages/{id}/reply": { "post": { "operationId": "postV1MessagesByIdReply", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachment_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array", "uniqueItems": true }, "body": { "type": "string" }, "html": { "maxLength": 1000000, "type": "string" }, "subaddress_instance_id": { "maxLength": 128, "minLength": 1, "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$", "type": "string" }, "subaddress_mode": { "enum": [ "reply_to", "from", "none" ], "type": "string" } }, "required": [ "body" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "daily_limit": { "type": "integer" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "hold_context": { "nullable": true, "properties": { "review_causes": { "items": { "enum": [ "content_warning", "first_contact", "send_window", "mailbox_policy" ], "type": "string" }, "nullable": true, "type": "array" }, "summary_reasons": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "trigger_source": { "enum": [ "mailbox_policy", "scanner", "both" ], "type": "string" } }, "required": [ "trigger_source", "summary_reasons" ], "type": "object" }, "html_sanitized": { "type": "boolean" }, "message_id": { "type": "string" }, "removed_categories": { "items": { "type": "string" }, "type": "array" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "sends_remaining": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "sent", "quarantined", "blocked", "pending_review" ], "type": "string" }, "warning": { "nullable": true, "type": "string" } }, "required": [ "message_id", "status", "daily_limit", "sends_remaining" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Reply to a message", "tags": [ "messages" ] } }, "/v1/messages/{id}/report": { "post": { "operationId": "postV1MessagesByIdReport", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "already_blocked": { "type": "boolean" }, "already_blocklisted": { "type": "boolean" }, "blocked": { "type": "boolean" }, "message_id": { "type": "string" }, "pattern_type": { "nullable": true, "type": "string" }, "sender_blocklisted": { "nullable": true, "type": "string" }, "state": { "type": "string" } }, "required": [ "message_id", "state", "blocked", "already_blocked", "sender_blocklisted", "already_blocklisted", "pattern_type" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: MAILBOX_ACCESS_DENIED)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Report and block an inbound message", "tags": [ "messages" ] } }, "/v1/messages/{id}/star": { "patch": { "operationId": "patchV1MessagesByIdStar", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "starred": { "type": "boolean" } }, "required": [ "starred" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message_id": { "type": "string" }, "starred": { "type": "boolean" } }, "required": [ "message_id", "starred" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Star or unstar a message", "tags": [ "messages" ] } }, "/v1/policy/overview": { "get": { "operationId": "getV1PolicyOverview", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "properties": { "custom_daily_send_limit": { "nullable": true, "type": "integer" }, "default_policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted", null ], "nullable": true, "type": "string" }, "resolved_default_policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted" ], "type": "string" } }, "required": [ "custom_daily_send_limit", "default_policy_mode", "resolved_default_policy_mode" ], "type": "object" }, "enforcement": { "properties": { "risky_only": { "enum": [ "off", "shadow", "enforce" ], "type": "string" }, "send_window": { "enum": [ "off", "shadow", "enforce" ], "type": "string" } }, "required": [ "risky_only", "send_window" ], "type": "object" }, "mailboxes": { "items": { "properties": { "address": { "type": "string" }, "blocked_this_week": { "properties": { "inbound": { "minimum": 0, "type": "integer" }, "outbound": { "minimum": 0, "type": "integer" } }, "required": [ "outbound", "inbound" ], "type": "object" }, "id": { "type": "string" }, "last_applied_policy_mode": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "pending_review_count": { "minimum": 0, "type": "integer" }, "policy_mode": { "enum": [ "read_only", "draft_only", "supervised", "trusted", "custom" ], "type": "string" }, "sender_policy_mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" } }, "required": [ "id", "name", "address", "policy_mode", "last_applied_policy_mode", "sender_policy_mode", "pending_review_count", "blocked_this_week" ], "type": "object" }, "type": "array" }, "recent_revisions": { "items": { "properties": { "actor_id": { "nullable": true, "type": "string" }, "actor_type": { "nullable": true, "type": "string" }, "containment_lever": { "enum": [ "off", "shadow", "enforce", null ], "nullable": true, "type": "string" }, "correction_of": { "nullable": true, "type": "string" }, "created_at": { "type": "string" }, "derived_mode": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "policy_change", "system_correction" ], "type": "string" }, "legacy_derivation": { "type": "boolean" }, "mailbox_id": { "nullable": true, "type": "string" }, "reauth_used": { "nullable": true, "type": "boolean" }, "scope": { "enum": [ "account", "mailbox" ], "type": "string" } }, "required": [ "id", "scope", "mailbox_id", "derived_mode", "kind", "legacy_derivation", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "mailboxes", "account", "enforcement", "recent_revisions" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Aggregated per-mailbox + account policy overview", "tags": [ "policy" ] } }, "/v1/recipients": { "get": { "operationId": "getV1Recipients", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "recipients": { "items": { "properties": { "confirmed_at": { "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "pending", "confirmed", "expired" ], "type": "string" } }, "required": [ "id", "email", "status", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "recipients" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List confirmed recipients", "tags": [ "recipients" ] }, "post": { "operationId": "postV1Recipients", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "maxLength": 512, "minLength": 1, "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "pending", "confirmed" ], "type": "string" } }, "required": [ "id", "email", "status", "created_at" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Add a confirmed recipient (admin)", "tags": [ "recipients" ] } }, "/v1/recipients/{id}": { "delete": { "operationId": "deleteV1RecipientsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "enum": [ "deleted" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Delete a recipient (admin)", "tags": [ "recipients" ] } }, "/v1/recipients/{id}/resend": { "post": { "operationId": "postV1RecipientsByIdResend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unavailable" } }, "summary": "Resend a recipient confirmation (admin)", "tags": [ "recipients" ] } }, "/v1/simulator/inbound": { "post": { "operationId": "postV1SimulatorInbound", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "label": { "description": "Optional correlation label appended, after sanitization, to the synthetic message subject. Use it to find an injection that returns pending.", "maxLength": 200, "type": "string" }, "mailbox_id": { "description": "Target mailbox name or UUID. Agent keys must be scoped to this mailbox.", "minLength": 1, "type": "string" }, "scenario": { "description": "clean exercises ordinary inbound ingestion. prompt_injection_quarantined exercises the real scanner with a prompt-injection fixture; use the returned status as the authoritative final state.", "enum": [ "clean", "prompt_injection_quarantined" ], "type": "string" } }, "required": [ "mailbox_id", "scenario" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message_id": { "description": "Present when scanning reaches available or quarantined within the bounded poll window.", "type": "string" }, "status": { "description": "available or quarantined is the resolved message state. pending means scanning continues asynchronously; use mailbox wait or list to find the labeled message.", "enum": [ "available", "quarantined", "pending" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Inject a synthetic inbound message (simulator)", "tags": [ "simulator" ] } }, "/v1/suppressions": { "get": { "operationId": "getV1Suppressions", "parameters": [ { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "reason", "required": false, "schema": { "enum": [ "hard_bounce", "complaint", "manual", "unsubscribe" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "next_cursor": { "nullable": true, "type": "string" }, "suppressions": { "items": { "properties": { "added_by_actor_id": { "nullable": true, "type": "string" }, "added_by_actor_type": { "nullable": true, "type": "string" }, "complaint_count": { "type": "number" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "latest_complaint_at": { "nullable": true, "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" } }, "required": [ "email", "reason", "source", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "suppressions" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: ACCOUNT_SUSPENDED, EMAIL_NOT_VERIFIED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List suppressed recipients", "tags": [ "suppressions" ] }, "post": { "operationId": "postV1Suppressions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "minLength": 1, "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "added_by_actor_id": { "nullable": true, "type": "string" }, "added_by_actor_type": { "nullable": true, "type": "string" }, "already_existed": { "type": "boolean" }, "created_at": { "nullable": true, "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" } }, "required": [ "email", "reason", "source", "created_at", "already_existed" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: ACCOUNT_SUSPENDED, EMAIL_NOT_VERIFIED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Suppress a recipient", "tags": [ "suppressions" ] } }, "/v1/suppressions/bulk": { "post": { "operationId": "postV1SuppressionsBulk", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "emails": { "items": { "maxLength": 254, "minLength": 1, "type": "string" }, "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "emails" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "added": { "items": { "properties": { "created_at": { "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" } }, "required": [ "email", "created_at" ], "type": "object" }, "type": "array" }, "already_existed": { "items": { "type": "string" }, "type": "array" }, "counts": { "properties": { "added": { "type": "integer" }, "already_existed": { "type": "integer" }, "invalid": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "added", "already_existed", "invalid", "total" ], "type": "object" }, "invalid": { "items": { "properties": { "email": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "email", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "added", "already_existed", "invalid", "counts" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: ACCOUNT_SUSPENDED, EMAIL_NOT_VERIFIED)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Bulk-suppress recipients", "tags": [ "suppressions" ] } }, "/v1/suppressions/{email}": { "delete": { "operationId": "deleteV1SuppressionsByEmail", "parameters": [ { "in": "path", "name": "email", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "type": "string" }, "email": { "type": "string" }, "pattern_type": { "enum": [ "email", "domain" ], "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "email" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Remove a suppression (admin)", "tags": [ "suppressions" ] } }, "/v1/threads/{id}": { "get": { "operationId": "getV1ThreadsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 512, "minLength": 1, "type": "string" } }, { "in": "query", "name": "body_format", "required": false, "schema": { "enum": [ "text", "html" ], "type": "string" } }, { "in": "query", "name": "body_page", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "include_firewall_blocked", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "mailbox", "required": false, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "in": "query", "name": "view", "required": false, "schema": { "enum": [ "summary", "verbose" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "type": "string" }, "mailbox_id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "message_count": { "type": "integer" }, "messages": { "items": { "properties": { "agent_safety_context": { "nullable": true, "properties": { "guidance": { "type": "string" }, "instruction_trust": { "additionalProperties": false, "properties": { "match": { "enum": [ "address" ], "type": "string" }, "provenance": { "enum": [ "managed" ], "type": "string" }, "verdict": { "enum": [ "verified_aligned" ], "type": "string" }, "verified_domain": { "nullable": true, "type": "string" }, "version": { "enum": [ "v1" ], "type": "string" } }, "required": [ "version", "match", "verified_domain", "verdict", "provenance" ], "type": "object" }, "untrusted_content": { "type": "boolean" } }, "required": [ "untrusted_content", "guidance" ], "type": "object" }, "attachments": { "items": { "properties": { "av_scanned_at": { "type": "string" }, "av_signature": { "type": "string" }, "av_verdict": { "enum": [ "clean", "infected", "error", "skipped" ], "type": "string" }, "content_disposition": { "type": "string" }, "content_id": { "type": "string" }, "content_type": { "type": "string" }, "declared_mime_type": { "type": "string" }, "filename": { "type": "string" }, "hash": { "type": "string" }, "inline": { "type": "boolean" }, "mime_mismatch": { "type": "boolean" }, "policy_action": { "enum": [ "deliver", "metadata_only", "quarantine", "block" ], "type": "string" }, "preview_char_count": { "nullable": true, "type": "integer" }, "preview_generated_at": { "format": "date-time", "nullable": true, "type": "string" }, "preview_kind": { "enum": [ "text", null ], "nullable": true, "type": "string" }, "preview_page_count": { "nullable": true, "type": "integer" }, "preview_reason_code": { "nullable": true, "type": "string" }, "preview_status": { "enum": [ "pending", "ready", "blocked", "failed", null ], "nullable": true, "type": "string" }, "preview_truncated": { "nullable": true, "type": "boolean" }, "raw_deleted_at": { "format": "date-time", "type": "string" }, "raw_retention": { "enum": [ "not_retained", "temporary_processing", "retained_for_raw_download" ], "type": "string" }, "raw_retention_reason": { "type": "string" }, "size": { "type": "integer" }, "sniffed_mime_type": { "type": "string" }, "stored": { "type": "boolean" } }, "required": [ "filename", "content_type", "size", "hash", "policy_action" ], "type": "object" }, "type": "array" }, "body": { "properties": { "char_count": { "type": "integer" }, "content": { "nullable": true, "type": "string" }, "format": { "enum": [ "text", "html" ], "type": "string" }, "returned_char_count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "format", "content", "char_count", "returned_char_count", "truncated" ], "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "dashboard_url": { "nullable": true, "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "type": "string" }, "email_effect": { "properties": { "effect_status": { "enum": [ "sent", "held_for_review", "held_infrastructure", "blocked" ], "type": "string" }, "releasable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "effect_status", "releasable", "terminal", "retryable" ], "type": "object" }, "firewall_block": { "additionalProperties": false, "nullable": true, "properties": { "envelope_sender": { "nullable": true, "type": "string" }, "from_address": { "nullable": true, "type": "string" }, "matched_field": { "enum": [ "envelope", "from", null ], "nullable": true, "type": "string" }, "matched_list": { "enum": [ "account_blocklist", "mailbox_allowlist", null ], "nullable": true, "type": "string" }, "matched_pattern": { "nullable": true, "type": "string" }, "mode": { "enum": [ "blocklist", "allowlist" ], "type": "string" }, "reason_code": { "enum": [ "SENDER_BLOCKED", "SENDER_NOT_ON_ALLOWLIST" ], "type": "string" } }, "required": [ "reason_code", "mode" ], "type": "object" }, "hold_context": { "nullable": true, "properties": { "review_causes": { "items": { "enum": [ "content_warning", "first_contact", "send_window", "mailbox_policy" ], "type": "string" }, "nullable": true, "type": "array" }, "summary_reasons": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "trigger_source": { "enum": [ "mailbox_policy", "scanner", "both" ], "type": "string" } }, "required": [ "trigger_source", "summary_reasons" ], "type": "object" }, "id": { "type": "string" }, "in_reply_to": { "nullable": true, "type": "string" }, "mailbox_id": { "type": "string" }, "mailbox_name": { "nullable": true, "type": "string" }, "read_at": { "nullable": true, "type": "string" }, "recipient": { "type": "string" }, "review_expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "review_outcome": { "enum": [ "approved", "denied", "expired", null ], "nullable": true, "type": "string" }, "review_reason": { "nullable": true, "type": "string" }, "review_trigger_source": { "enum": [ "mailbox_policy", "scanner", "both", null ], "nullable": true, "type": "string" }, "reviewed_at": { "nullable": true, "type": "string" }, "reviewed_by_id": { "nullable": true, "type": "string" }, "reviewed_by_type": { "nullable": true, "type": "string" }, "scan": { "nullable": true, "properties": { "categories": { "items": { "properties": { "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" } }, "required": [ "category", "decision" ], "type": "object" }, "type": "array" }, "findings": { "items": { "properties": { "agent_instructions": { "items": { "type": "string" }, "type": "array" }, "attachment_filename": { "type": "string" }, "attachment_index": { "minimum": 0, "type": "integer" }, "attachment_policy_action": { "enum": [ "quarantine_message", "metadata_only_after_rewrite", "derived_text_finding" ], "type": "string" }, "category": { "type": "string" }, "decision": { "enum": [ "allow", "allow_with_warning", "quarantine", "require_human_approval", "block" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_class": { "enum": [ "inference_error", "model_judgment" ], "type": "string" }, "pii_type": { "enum": [ "ssn", "credit_card", "phone_number" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "retryable": { "type": "boolean" }, "subtype": { "type": "string" }, "warning": { "properties": { "affected_urls": { "items": { "type": "string" }, "type": "array" }, "attribution_text": { "type": "string" }, "attribution_url": { "type": "string" }, "learn_more": { "items": { "properties": { "threat_type": { "enum": [ "MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "SOCIAL_ENGINEERING_EXTENDED_COVERAGE" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "threat_type", "url" ], "type": "object" }, "type": "array" }, "qualified_wording": { "type": "string" } }, "required": [ "qualified_wording", "attribution_text", "attribution_url", "learn_more", "affected_urls" ], "type": "object" } }, "required": [ "category", "decision", "reason" ], "type": "object" }, "type": "array" }, "verdict": { "enum": [ "clean", "warning", "review_required", "blocked", "quarantined" ], "type": "string" } }, "required": [ "verdict", "categories", "findings" ], "type": "object" }, "sender": { "type": "string" }, "sender_authentication": { "additionalProperties": false, "nullable": true, "properties": { "from_domain": { "nullable": true, "type": "string" }, "provenance": { "enum": [ "managed", "self_hosted_imap", null ], "nullable": true, "type": "string" }, "signing_domain": { "nullable": true, "type": "string" }, "verdict": { "enum": [ "verified_aligned", "authenticated_unaligned", "failed", "none", "error", null ], "nullable": true, "type": "string" } }, "required": [ "verdict", "provenance" ], "type": "object" }, "starred": { "type": "boolean" }, "state": { "type": "string" }, "subaddress_instance_id": { "nullable": true, "type": "string" }, "subject": { "type": "string" }, "thread_id": { "nullable": true, "type": "string" } }, "required": [ "id", "direction", "state", "sender", "recipient", "subject", "body", "created_at" ], "type": "object" }, "type": "array" }, "subject": { "type": "string" } }, "required": [ "id", "mailbox_id", "subject", "message_count", "messages" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden (code: INSUFFICIENT_SCOPE)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get a thread", "tags": [ "threads" ] } }, "/v1/webhooks": { "get": { "operationId": "getV1Webhooks", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "webhooks": { "items": { "properties": { "consecutive_failures": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "nullable": true, "type": "string" }, "disabled_at": { "format": "date-time", "nullable": true, "type": "string" }, "disabled_reason": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "enabled_events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "last_error": { "nullable": true, "type": "string" }, "last_failure_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "format": "date-time", "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "enabled", "enabled_events", "created_at", "updated_at", "consecutive_failures" ], "type": "object" }, "type": "array" } }, "required": [ "webhooks" ], "type": "object" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List webhooks", "tags": [ "webhooks" ] }, "post": { "operationId": "postV1Webhooks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "maxLength": 200, "type": "string" }, "enabled": { "type": "boolean" }, "enabled_events": { "items": { "enum": [ "message.received", "message.delivered", "message.bounced", "message.quarantined", "message.scanner_blocked", "attachment.preview.queued", "attachment.preview.ready", "attachment.preview.blocked", "attachment.preview.failed", "recipient_blocklist.added", "recipient_blocklist.removed", "recipient_blocklist.complaint_override", "recipient_allowlist.added", "recipient_allowlist.removed", "mailbox.recipient_policy_changed", "recipient_allowlist.blocked_attempt", "message.scheduled", "message.rescheduled", "message.schedule_cancelled", "message.dispatch_failed", "domain.self_hosted_auth_failed", "domain.self_hosted_probe_failed", "inbound_sender.blocked", "sender_allowlist.added", "sender_allowlist.removed", "sender_blocklist.added", "sender_blocklist.removed", "mailbox.sender_policy_changed", "legal_hold.applied", "legal_hold.released", "message.review.queued", "message.review.approved", "message.review.denied", "message.review.expired", "message.released", "mailbox.policy_changed", "trusted_source.granted", "trusted_source.revoked", "webhook.test" ], "type": "string" }, "type": "array", "uniqueItems": true }, "url": { "maxLength": 2048, "minLength": 1, "type": "string" } }, "required": [ "url", "enabled_events" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "enabled_events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "signing_secret": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "enabled", "enabled_events", "signing_secret", "created_at" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Create a webhook", "tags": [ "webhooks" ] } }, "/v1/webhooks/{id}": { "delete": { "operationId": "deleteV1WebhooksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "enum": [ "deleted" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Delete a webhook", "tags": [ "webhooks" ] }, "get": { "operationId": "getV1WebhooksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "consecutive_failures": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "nullable": true, "type": "string" }, "disabled_at": { "format": "date-time", "nullable": true, "type": "string" }, "disabled_reason": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "enabled_events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "last_error": { "nullable": true, "type": "string" }, "last_failure_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "format": "date-time", "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "enabled", "enabled_events", "created_at", "updated_at", "consecutive_failures" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Get a webhook", "tags": [ "webhooks" ] }, "patch": { "operationId": "patchV1WebhooksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "maxLength": 200, "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "enabled_events": { "items": { "enum": [ "message.received", "message.delivered", "message.bounced", "message.quarantined", "message.scanner_blocked", "attachment.preview.queued", "attachment.preview.ready", "attachment.preview.blocked", "attachment.preview.failed", "recipient_blocklist.added", "recipient_blocklist.removed", "recipient_blocklist.complaint_override", "recipient_allowlist.added", "recipient_allowlist.removed", "mailbox.recipient_policy_changed", "recipient_allowlist.blocked_attempt", "message.scheduled", "message.rescheduled", "message.schedule_cancelled", "message.dispatch_failed", "domain.self_hosted_auth_failed", "domain.self_hosted_probe_failed", "inbound_sender.blocked", "sender_allowlist.added", "sender_allowlist.removed", "sender_blocklist.added", "sender_blocklist.removed", "mailbox.sender_policy_changed", "legal_hold.applied", "legal_hold.released", "message.review.queued", "message.review.approved", "message.review.denied", "message.review.expired", "message.released", "mailbox.policy_changed", "trusted_source.granted", "trusted_source.revoked", "webhook.test" ], "type": "string" }, "type": "array", "uniqueItems": true }, "url": { "maxLength": 2048, "minLength": 1, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "consecutive_failures": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "nullable": true, "type": "string" }, "disabled_at": { "format": "date-time", "nullable": true, "type": "string" }, "disabled_reason": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "enabled_events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "last_error": { "nullable": true, "type": "string" }, "last_failure_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "format": "date-time", "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "enabled", "enabled_events", "created_at", "updated_at", "consecutive_failures" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Update a webhook", "tags": [ "webhooks" ] } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "getV1WebhooksByIdDeliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "in": "query", "name": "before_at", "required": false, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "before_id", "required": false, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deliveries": { "items": { "properties": { "attempt_count": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "format": "date-time", "nullable": true, "type": "string" }, "event_type": { "type": "string" }, "failed_at": { "format": "date-time", "nullable": true, "type": "string" }, "http_status": { "nullable": true, "type": "integer" }, "id": { "type": "string" }, "next_retry_at": { "format": "date-time", "nullable": true, "type": "string" }, "response_preview": { "nullable": true, "type": "string" }, "status": { "enum": [ "pending", "delivering", "delivered", "failed" ], "type": "string" } }, "required": [ "id", "event_type", "status", "attempt_count", "created_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_before_at": { "format": "date-time", "type": "string" }, "next_before_id": { "type": "string" } }, "required": [ "deliveries", "has_more" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "List webhook deliveries", "tags": [ "webhooks" ] } }, "/v1/webhooks/{id}/deliveries/{delivery_id}/retry": { "post": { "operationId": "postV1WebhooksByIdDeliveriesByDeliveryIdRetry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "delivery_id": { "type": "string" }, "status": { "enum": [ "pending" ], "type": "string" } }, "required": [ "delivery_id", "status" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Retry a failed webhook delivery", "tags": [ "webhooks" ] } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "operationId": "postV1WebhooksByIdRotateSecret", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "signing_secret": { "type": "string" } }, "required": [ "signing_secret" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error" } }, "summary": "Rotate a webhook signing secret", "tags": [ "webhooks" ] } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "postV1WebhooksByIdTest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "nullable": true, "properties": { "event": { "enum": [ "message.delivered", "message.bounced", "recipient_blocklist.added" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "delivery_id": { "type": "string" } }, "required": [ "delivery_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation error (code: VALIDATION_ERROR)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key (code: UNAUTHORIZED)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited (code: RATE_LIMITED)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal error (code: INTERNAL_ERROR)" } }, "summary": "Send a test webhook delivery", "tags": [ "webhooks" ] } } }, "security": [ { "BearerApiKey": [] } ], "servers": [ { "description": "Production", "url": "https://api.replylayer.ai" } ], "tags": [ { "name": "account" }, { "name": "attachments" }, { "name": "domains" }, { "name": "drafts" }, { "name": "inbound-firewall" }, { "name": "legal-holds" }, { "name": "mailboxes" }, { "name": "messages" }, { "name": "policy" }, { "name": "recipient-allowlist" }, { "name": "recipients" }, { "name": "simulator" }, { "name": "suppressions" }, { "name": "threads" }, { "name": "webhooks" } ] }