{ "openapi": "3.1.1", "info": { "title": "Cherami HTTP API", "version": "1.0.0", "description": "Email infrastructure for AI agents. This contract describes public HTTP operations, not MCP projections or browser-session adapters. HTTP success does not prove provider acceptance or delivery. Use the operation-specific recovery rules.", "contact": { "name": "Cherami", "email": "hello@cherami.to" } }, "servers": [ { "url": "https://cherami.to" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "access" }, { "name": "inboxes" }, { "name": "messages" }, { "name": "labels" }, { "name": "sending" }, { "name": "drafts" }, { "name": "threads" }, { "name": "feedback" } ], "paths": { "/v1/signups": { "post": { "operationId": "discoverSignup", "tags": [ "access" ], "summary": "Find the approval page", "description": "Agents can give humans **https://cherami.to/claim** directly, or call `POST /v1/signups` with an empty object:\n\nReturns `202` with `status: \"awaiting_human\"`, `approval_url: \"https://cherami.to/claim\"`, and a guidance `message`. No email is sent and no account or pending request is created. Unknown fields return `400 invalid_request`.\n\nThe human signs in and explicitly approves account-wide API access. The page shows the verified email. Existing keys keep working when another key is issued. A recent sign-in or Clerk reverification is required. It displays a six-word phrase once, valid for 6 hours. The human chooses which agent receives it.\n\nOpening the page grants nothing. Do not ask for sign-in codes, approve for the human, or poll for signup status. Limit: 10 discovery requests per IP/hour; 10 browser approval requests per IP/15 minutes. `429` includes `Retry-After`.", "parameters": [], "responses": { "202": { "description": "Request accepted; inspect the response for its meaning.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResult" }, "example": { "status": "awaiting_human", "approval_url": "https://cherami.to/claim", "message": "Example" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_request`: Signup or claim contains unsupported fields. Signup accepts only an empty object.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`origin_not_allowed`: Signup/claim requests with an Origin header must use Cherami's origin. Use the hosted Claim page for human approval.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: Signup discovery or claim attempts exceeded their limit. Respect `Retry-After`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay in seconds when supplied. Quota uses sufficient_capacity_at; absent when waiting cannot make the message fit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "origin_not_allowed", "rate_limited", "invalid_json", "body_too_large", "unsupported_media_type", "invalid_request", "internal_error" ], "security": [], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 4096 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupInput" }, "example": {} } } }, "x-request-body-limit": 4096, "x-example-body": {} } }, "/v1/claims": { "post": { "operationId": "redeemClaim", "tags": [ "access" ], "summary": "Redeem a claim phrase", "description": "`phrase` is required. Case and whitespace differences are accepted. Returns `201` with `account_id`, `credential`, `token_type: \"Bearer\"`, and a guidance `message`. Credential values are deliberately not shown in documentation examples.\n\nStore the credential immediately in private storage. It is returned once. Do not print it in chat, logs, code, or commits. Human approval creates an account if needed. Each redemption issues an additional account-wide key. Existing keys, account identity, inboxes, mail, and shared allowances stay unchanged.\n\nEach phrase works once. Redeeming it does not invalidate other approved phrases. Lost credentials or successful claim responses require another [human-approved recovery](https://cherami.to/docs/guides/recovery), not an automatic claim retry. Claims do not allocate an inbox: list inboxes first.\n\nLimit: 10 claim attempts per IP/15 minutes. Invalid, expired, or used phrases cannot issue credentials. Errors include `400 invalid_claim` for an invalid, expired, used, or no longer eligible phrase and `429 rate_limited` for rate limiting; follow the returned guidance. See the [HTTP error catalog](https://cherami.to/docs/api/errors#error-codes).\n\n### Optional signup research\n\nWhen this Claim approval created the account, the claim body may also include `discovery_source` and `intended_use`.\n\nThese are optional plain-text answers of at most 500 UTF-16 code units each, trimmed before collection. Use brief answers from existing context. Omit unknown answers, leave them blank, or write `unknown`. Do not guess, interrupt the human, or include secrets or private conversation excerpts.\n\nBlank, malformed, or overlong answers are ignored. Collection is best effort and does not gate credential issuance. Recovery and a first API key for a pre-existing MCP account ignore them and preserve original answers. Never repeat a claim to save research.\n\nThe answers help understand discovery and intended uses, not assess trust or abuse. They are agent-supplied research, not verified human intent or a commitment about future use. [Privacy and removal](https://cherami.to/privacy)", "parameters": [], "responses": { "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResult" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_request`: Signup or claim contains unsupported fields. Signup accepts only an empty object.\n\n`invalid_claim`: Phrase is invalid, expired, used, or no longer eligible. Ask the human for a fresh approval.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`origin_not_allowed`: Signup/claim requests with an Origin header must use Cherami's origin. Use the hosted Claim page for human approval.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: Signup discovery or claim attempts exceeded their limit. Respect `Retry-After`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay in seconds when supplied. Quota uses sufficient_capacity_at; absent when waiting cannot make the message fit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "origin_not_allowed", "rate_limited", "invalid_json", "body_too_large", "unsupported_media_type", "invalid_request", "invalid_claim", "internal_error" ], "security": [], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 4096 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimInput" }, "example": { "phrase": "THE SIX WORDS FROM YOUR HUMAN" } } } }, "x-request-body-limit": 4096, "x-example-body": { "phrase": "THE SIX WORDS FROM YOUR HUMAN" } } }, "/v1/inboxes": { "get": { "operationId": "listInboxes", "tags": [ "inboxes" ], "summary": "List inboxes", "description": "`GET /v1/inboxes` returns `200`.\n\nThis list is not paginated. Use the returned `inbox_limit` as authoritative. `inbox_allowance` reports the cap, occupied slots and remaining slots as a current snapshot, not a reservation. List before creating or when recovering an uncertain allocation. Agents should use the human's assigned inbox, not assume every listed inbox is theirs to take over.", "parameters": [], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxList" }, "example": { "inboxes": [], "inbox_limit": 0, "inbox_allowance": { "allowance": 0, "used": 0, "remaining": 0, "unit": "inbox_slots" } } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "internal_error" ] }, "post": { "operationId": "createInbox", "tags": [ "inboxes" ], "summary": "Create an inbox", "description": "Both names accept Unicode text up to 256 UTF-8 bytes after trimming, without control characters. Omitted, null and blank names mean no name at creation. Existing inboxes without names return null for both fields. Names need not be unique. Unknown fields are rejected.\n\nAddresses are globally unique. `hello`, `test`, `reviewer_chatgpt` and prefixes beginning `reviewer_chatgpt_` are reserved; retired addresses cannot be reused. No custom domains or allocated-address renaming are supported. To replace an address while keeping the old inbox during transition, see [Change your agent's email address](https://cherami.to/docs/guides/change-email-address).\n\nNew creation returns `201` with the inbox object and `Location: /v1/inboxes/{id}`. `400` means invalid input. `409` covers unavailable addresses, the inbox cap and key conflicts. A definitive `address_unavailable` permits choosing another prefix; do not create accounts to evade a cap.\n\nAn inbox-cap failure has `error.code: \"inbox_limit_reached\"` and `error.details` containing `allowance` (the same shape as `inbox_allowance`), `increase_request` and `policy_url`. Request additional slots for another workflow or an address transition rather than retiring an inbox you still need. See [Free and custom allowances](https://cherami.to/pricing).\n\n### Recover creation\n\nCreation keys are scoped to the authenticated account across HTTP and MCP, independently of sending keys. Protection lasts **24 hours from successful allocation**, without renewal. Keyed results add `replayed` and `idempotency_expires_at`. Initial creation returns `201` with `replayed: false`; a matching retry returns `200` with `replayed: true` and the original inbox ID. Both supply `Location`.\n\nA replay returns the inbox's **current state**, not a frozen creation response. Later name edits are preserved. Retry with the original creation inputs, not those edited names. JSON property order is irrelevant; address-prefix case and surrounding whitespace, trimmed name whitespace, and absent/null/blank names normalize equivalently. Different validated inputs return `409 idempotency_conflict`.\n\nDeleting the inbox does not free an active key. A matching retry returns `409 idempotency_result_unavailable`, never allocates a replacement and never restores the deleted inbox. Concurrent matching requests allocate only one inbox and consume one slot.\n\nIf creation's outcome is uncertain, reuse the original key and unchanged payload **within 24 hours of your first request**. Do not replace the key or choose another address to resolve uncertainty. Validation and allocation failures that definitely precede creation do not consume a key; an infrastructure error may follow successful creation.\n\nAfter expiry, the key no longer protects a request. List inboxes and reconcile the intended address instead of blindly creating again. An existing or retired address remains unavailable, but that is not a replay result. Unkeyed creation is supported: another request for the same address conflicts rather than returning the original resource. If its response was lost, list inboxes before deciding what to do.", "parameters": [], "responses": { "200": { "description": "Matching replay: current resource or saved attempt, without another allocation or provider submission.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreatedInbox" }, { "type": "object", "properties": { "replayed": { "const": true }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "replayed", "idempotency_expires_at" ] } ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "local_part": "my-agent", "address": "my-agent@cherami.to", "name": null, "sender_name": null, "created_at": "2026-10-01T00:00:00.000Z", "replayed": true, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreatedInbox" }, { "type": "object", "properties": { "replayed": { "const": false } }, "required": [] } ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "local_part": "my-agent", "address": "my-agent@cherami.to", "name": null, "sender_name": null, "created_at": "2026-10-01T00:00:00.000Z", "replayed": false, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_inbox`: Use supported inbox fields; editing requires at least one name field.\n\n`invalid_local_part`: Correct the requested [address prefix](https://cherami.to/docs/api/inboxes/create-inbox).\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.\n\n`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`address_unavailable`: Choose another address prefix; this address cannot be allocated.\n\n`inbox_limit_reached`: Read `error.details.allowance` for occupied and remaining slots; [request an increase](https://cherami.to/docs/guides/support) if needed.\n\n`idempotency_conflict`: The key belongs to different input. Recover with the original inbox and payload, not a replacement key.\n\n`idempotency_result_unavailable`: The key was used but its inbox, draft or sent copy is unavailable. No replacement was created or submitted; do not bypass protection with a new key.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxError" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "invalid_inbox", "invalid_local_part", "invalid_name", "invalid_idempotency_key", "address_unavailable", "inbox_limit_reached", "idempotency_conflict", "idempotency_result_unavailable", "not_found", "internal_error" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 4096 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInbox" }, "example": { "local_part": "my-agent", "name": "Research", "idempotency_key": "RETAIN_A_UNIQUE_CREATION_KEY" } } } }, "x-request-body-limit": 4096, "x-example-body": { "local_part": "my-agent", "name": "Research", "idempotency_key": "RETAIN_A_UNIQUE_CREATION_KEY" } } }, "/v1/inboxes/{inbox_id}": { "get": { "operationId": "getInbox", "tags": [ "inboxes" ], "summary": "Read an inbox", "description": "Returns the owned inbox’s address and current names. Missing, deleted and other-account resources return 404. Names do not isolate agents or change ownership.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "local_part": "my-agent", "address": "my-agent@cherami.to", "name": null, "sender_name": null, "created_at": "2026-10-01T00:00:00.000Z" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "internal_error" ] }, "patch": { "operationId": "updateInbox", "tags": [ "inboxes" ], "summary": "Edit inbox names", "description": "Supply one or both editable names.\n\nReturns `200` with the updated inbox. Omitted fields stay unchanged; null or blank clears a name. The same name limits apply as at creation. An empty object, unknown fields, address or `local_part` changes are rejected. If an update's response is lost, read the inbox before repeating a change that could overwrite another editor's work.\n\nNeither name changes ownership or permissions. A sender-name edit affects subsequent submissions, not historical mail or a replayed send. A send already in progress may retain the earlier name.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "local_part": "my-agent", "address": "my-agent@cherami.to", "name": null, "sender_name": null, "created_at": "2026-10-01T00:00:00.000Z" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_inbox`: Use supported inbox fields; editing requires at least one name field.\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "invalid_inbox", "invalid_name", "internal_error" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 4096 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInbox" }, "example": { "name": "Travel correspondence", "sender_name": null } } } }, "x-request-body-limit": 4096, "x-example-body": { "name": "Travel correspondence", "sender_name": null } }, "delete": { "operationId": "deleteInbox", "tags": [ "inboxes" ], "summary": "Delete an inbox", "description": "`DELETE /v1/inboxes/{inbox_id}` returns `202`.\n\nPermanently deletes the inbox and its received mail, drafts, sent copies, attachments, and threads, including unfinished messages. Confirm the specific inbox and destructive scope with the human before calling it, especially with shared access. The API does not provide a separate approval step.\n\nThe slot is freed and the address is permanently retired. Future incoming mail is rejected. Retrieval and new sends from the deleted inbox return `404`. Other inboxes and the credential remain unchanged. There is no undo or sending-quota refund.\n\nRepeating DELETE is safe and can return `202` or `404`. Missing or other-account resources also return `404`. The service support inbox `hello@cherami.to` returns `409 protected_inbox` to its owner.\n\n[Deletion guide and manual account deletion](https://cherami.to/docs/guides/deletion)", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "202": { "description": "Request accepted; inspect the response for its meaning.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "status": "deletion_pending", "message": "Example" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`protected_inbox`: The service support inbox cannot be deleted.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "operation_not_allowed", "protected_inbox", "internal_error" ] } }, "/v1/inboxes/{inbox_id}/sending-policy": { "get": { "operationId": "getSendingPolicy", "tags": [ "inboxes" ], "summary": "Inspect sending rules", "description": "`GET /v1/inboxes/{inbox_id}/sending-policy` returns `200`.\n\n`enabled: false` means unrestricted by this control, even when saved addresses or domains remain. When enabled, every To/Cc/Bcc recipient must match an exact address or an exact domain; both lists empty blocks all sending. Local-part case is significant, domain case is not, and plus tags/dots remain distinct. Names do not participate in matching. Each list contains at most 100 normalized, unique entries. Domains are lowercase ASCII, including punycode; matching does not include subdomains unless listed separately.\n\n`revision` is the saved policy version, starting at `0` for an unconfigured inbox. Inspection is not authorization for a later send: the policy at send reservation is authoritative. Missing, deleted and other-account inboxes return `404`.\n\nThis endpoint is read-only. Only the human’s browser session can edit rules in [Account → Sending rules](https://cherami.to/account/sending-rules), not an API key or OAuth mail grant. New inboxes start unrestricted. See [recipient restrictions](https://cherami.to/docs/guides/sending-rules) for setup and scope.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" }, "example": { "inbox_id": "11111111-1111-4111-8111-111111111111", "enabled": true, "addresses": [], "domains": [], "revision": 0 } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "internal_error" ] } }, "/v1/inboxes/{inbox_id}/receiving-policy": { "get": { "operationId": "getReceivingPolicy", "tags": [ "inboxes" ], "summary": "Inspect receiving rules", "description": "`GET /v1/inboxes/{inbox_id}/receiving-policy` returns `200`.\n\n`enabled: false` pauses blocking without clearing either saved list. When enabled, any supported parsed From address matching an exact address **or** exact domain rejects the incoming mail. Empty lists block nothing. Local-part case matters; domain case does not. Plus tags and dots stay distinct. Each list has at most 100 normalized, unique entries. Domains are lowercase ASCII, including punycode, with no implicit subdomain matching.\n\n`revision` is the saved version, starting at `0` for an unconfigured inbox. Missing, deleted and other-account inboxes return `404`. Inspection is read-only and cannot promise the policy for a later receipt.\n\nOnly the human’s browser session can edit rules in [Account → Receiving rules](https://cherami.to/account/receiving-rules), not an API key or OAuth mail grant. See [receiving rules](https://cherami.to/docs/guides/receiving-rules) for parsing boundaries and rejection behavior. From is sender-controlled, not authenticated identity; existing messages are never hidden or deleted by a policy change.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" }, "example": { "inbox_id": "11111111-1111-4111-8111-111111111111", "enabled": true, "addresses": [], "domains": [], "revision": 0 } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "internal_error" ] } }, "/v1/inboxes/{inbox_id}/messages": { "get": { "operationId": "listMessages", "tags": [ "messages" ], "summary": "List received messages", "description": "Returns `200` with `messages` and `next_cursor`. Messages default to newest-received first. Combine keyword search, sender, recipient, subject, date and label filters; `order` accepts `newest`, `oldest`, or `relevance`. See [search and filtering](https://cherami.to/docs/guides/search). `limit` is 1–100, default 20. Follow the returned cursor as a URL-encoded `cursor` parameter on the same URL. Use `labels_all` for required tags, optionally combined with `labels_any` and `labels_none`. Keep the same filters when following a cursor. See [pagination](https://cherami.to/docs/api/errors#pagination) and [label filtering](https://cherami.to/docs/guides/labels).\n\nThe response schema describes every summary field. `subject` may be null. `thread_id` is null until parsing succeeds. Only ready summaries additionally contain `from`, with a parsed address or null if absent. It is omitted for other states.\n\nA parsed address is a mailbox (`{\"name\":\"Sender\",\"address\":\"sender@example.com\"}`) or group (`{\"name\":\"Team\",\"group\":[{\"name\":\"Sender\",\"address\":\"sender@example.com\"}]}`). Parsed From is sender-supplied, not proof of identity. `envelope_from` is the SMTP sender and may be a bounce address.\n\n### Previews\n\nBoth received and sent listings include `preview`: null when derived content is not ready or unavailable, otherwise an object:\n\n`text` is the beginning of the extracted reply when available, otherwise the plain-text body or text derived from HTML. Whitespace is normalized and the excerpt is capped at 300 Unicode code points, preferably at a word boundary. `source` is `reply_text`, `text`, or `html`; `truncated` indicates that the chosen text exceeded the excerpt. A short excerpt may contain the whole chosen text, not necessarily the whole original email. A genuinely empty extracted reply produces `text: \"\"`, not null. Previews are deterministic excerpts, not summaries or read/unread state.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Decimal integer without signs, whitespace or leading zeroes." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nonempty lexical subject/body search, at most 512 UTF-16 code units and 16 words or closed quoted phrases. Every term must match; no raw FTS operators. Attachments and filenames are excluded." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope." }, { "name": "recipient", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope." }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive literal substring, nonblank and at most 998 UTF-16 code units before trimming." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "description": "Inclusive lower service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "description": "Exclusive upper service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets." }, { "name": "labels_all", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Require every listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "labels_any", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Require at least one listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "labels_none", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Exclude any message carrying a listed label; unlabeled messages qualify. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "newest", "oldest", "relevance" ], "default": "newest" }, "description": "relevance requires query. Listings are live views, not snapshots." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedSummary" } }, "next_cursor": { "anyOf": [ { "type": "string", "description": "Opaque cursor; preserve resource, filters and order." }, { "type": "null" } ] } }, "required": [ "messages", "next_cursor" ] }, "example": { "messages": [], "next_cursor": null } } } }, "400": { "description": "`invalid_limit`: Use an integer from 1 to 100.\n\n`invalid_cursor`: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.\n\n`invalid_search`: Correct search terms, filters, timestamps, or ordering. See [search](https://cherami.to/docs/guides/search).\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "invalid_limit", "invalid_cursor", "invalid_search", "invalid_labels", "internal_error" ] } }, "/v1/inboxes/{inbox_id}/messages/count": { "get": { "operationId": "countMessages", "tags": [ "messages" ], "summary": "Count received messages", "description": "`GET /v1/inboxes/{inbox_id}/messages/count` returns `200` with `{\"count\":3}`.\n\nThe same search and filters as the received list apply, including combined and exclusion filters. This is the current count, including unfinished messages, not an unread count or a snapshot shared with pagination.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nonempty lexical subject/body search, at most 512 UTF-16 code units and 16 words or closed quoted phrases. Every term must match; no raw FTS operators. Attachments and filenames are excluded." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope." }, { "name": "recipient", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope." }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive literal substring, nonblank and at most 998 UTF-16 code units before trimming." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "description": "Inclusive lower service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "description": "Exclusive upper service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets." }, { "name": "labels_all", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Require every listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "labels_any", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Require at least one listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "labels_none", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Exclude any message carrying a listed label; unlabeled messages qualify. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] }, "example": { "count": 0 } } } }, "400": { "description": "`invalid_search`: Correct search terms, filters, timestamps, or ordering. See [search](https://cherami.to/docs/guides/search).\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "invalid_search", "invalid_labels", "internal_error" ] } }, "/v1/messages/{message_id}": { "get": { "operationId": "getMessage", "tags": [ "messages" ], "summary": "Read a received message", "description": "Returns received metadata, raw size and processing completion time. The list-only `from` and `preview` are omitted.\n\nReady content includes original prepared bodies, parsed header values, extracted reply text and attachment metadata. Unfinished and failed detail responses omit content.\n\nEach received attachment has `id` (string), `filename` (string or null), `size` (bytes), `mime_type`, `disposition` (string or null), `content_id` (string or null), and `related` (boolean). Use its `id` in the attachment download route.\n\nReply extraction preserves original bodies and does not change full-body search. It prefers plain text and derives text from HTML-only mail without rendering or fetching resources. It can miss unusual quoting or omit inline answers; read `text` or `html` when the full context matters. Explicitly marked forwards are retained rather than treated as quoted replies. Extraction failure does not fail ordinary retrieval.\n\n### Processing states\n\n`pending` and `processing` mean prepared content is not ready. Check later with bounded backoff. `ready` supplies `content`; `failed` does not. All four states can return detail `200`. Raw MIME remains available in unfinished and failed states. Missing stored content can return `503 content_unavailable`.", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedDetail" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "thread_id": null, "envelope_from": "sender@example.com", "envelope_to": "my-agent@cherami.to", "subject": null, "received_at": "2026-10-01T00:00:00.000Z", "processing_status": "ready", "labels": [], "message_id": null, "raw_size": 0, "processed_at": null, "content": { "from": null, "sender": null, "reply_to": [], "to": [], "cc": [], "bcc": [], "subject": null, "message_id": null, "in_reply_to": null, "references": null, "date": null, "reply_text": null, "text": null, "html": null, "attachments": [] } } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "content_unavailable", "internal_error" ] }, "delete": { "operationId": "deleteMessage", "tags": [ "messages" ], "summary": "Delete a received message", "description": "`DELETE /v1/messages/{message_id}` returns `202`.\n\nPermanently deletes the received message and its attachments, including when parsing is unfinished. No trash or undo. It is no longer available for retrieval or as a new reply target. Repeated deletion is safe and can return `202` or `404`.\n\n[Receiving guide](https://cherami.to/docs/guides/receiving) · [Deletion guide](https://cherami.to/docs/guides/deletion)", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "202": { "description": "Request accepted; inspect the response for its meaning.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "status": "deletion_pending", "message": "Example" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "operation_not_allowed", "internal_error" ] }, "patch": { "operationId": "updateMessageLabels", "tags": [ "labels" ], "summary": "Label a received message", "description": "Adds or removes labels on a received message. Use `Content-Type: application/json` with a body up to 20 KiB.\n\nAt least one array must contain a label. Unknown fields are rejected. Duplicate names within an array are ignored. A name cannot appear in both arrays after trimming.\n\nNames must contain 1–128 UTF-8 bytes after trimming surrounding whitespace, with no control characters or malformed Unicode. Case is preserved: `Receipts` and `receipts` are different tags. Labels are a set; do not rely on their order.\n\nA successful update returns `200` with the message ID and resulting labels. Additions and removals apply together without replacing unrelated labels. Repeating the same update does not duplicate labels. Concurrent changes to different labels are preserved; opposite changes to the same label follow write order. Labels are not a work-claiming lock.\n\nInvalid changes return `400 invalid_labels`. Missing, deleted, or other-account messages return `404`. Label updates do not require sending or deletion permission and consume no sending allowance.", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResult" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "labels": [] } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "invalid_labels", "internal_error" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 20480 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelChange" }, "example": { "add_labels": [ "handled" ], "remove_labels": [ "needs-review" ] } } } }, "x-request-body-limit": 20480, "x-example-body": { "add_labels": [ "handled" ], "remove_labels": [ "needs-review" ] } } }, "/v1/messages/{message_id}/raw": { "get": { "operationId": "downloadRawMessage", "tags": [ "messages" ], "summary": "Download raw MIME", "description": "Returns `200` with original MIME bytes, `Content-Type: message/rfc822`, and attachment disposition. This does not require successful parsing.", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Original bytes, served as a download.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Content-Disposition": { "schema": { "type": "string" }, "description": "Attachment disposition with a safely encoded suggested filename." }, "Content-Length": { "schema": { "type": "integer", "minimum": 0 }, "description": "Original byte count." }, "Cache-Control": { "schema": { "type": "string" }, "description": "Includes no-store." }, "X-Content-Type-Options": { "schema": { "const": "nosniff" } }, "Content-Security-Policy": { "schema": { "type": "string" }, "description": "Sandbox with default-src 'none'." } }, "content": { "message/rfc822": {} } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "content_unavailable", "internal_error" ] } }, "/v1/messages/{message_id}/attachments/{attachment_id}": { "get": { "operationId": "downloadAttachment", "tags": [ "messages" ], "summary": "Download a received attachment", "description": "Returns `200` with file bytes, `Content-Type: application/octet-stream`, and attachment disposition. Use the ID returned in ready content, not a guessed filename. An unavailable attachment or a message that is not ready returns `404`; missing stored content can return `503`.\n\nDownloads use `no-store`, `nosniff`, and a sandbox content security policy. Reported filenames and MIME metadata do not establish that files are safe to execute or render.", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID from received attachment metadata, not a filename." } ], "responses": { "200": { "description": "Original bytes, served as a download.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Content-Disposition": { "schema": { "type": "string" }, "description": "Attachment disposition with a safely encoded suggested filename." }, "Content-Length": { "schema": { "type": "integer", "minimum": 0 }, "description": "Original byte count." }, "Cache-Control": { "schema": { "type": "string" }, "description": "Includes no-store." }, "X-Content-Type-Options": { "schema": { "const": "nosniff" } }, "Content-Security-Policy": { "schema": { "type": "string" }, "description": "Sandbox with default-src 'none'." } }, "content": { "application/octet-stream": {} } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "content_unavailable", "internal_error" ] } }, "/v1/sent/{message_id}": { "delete": { "operationId": "deleteSentMessage", "tags": [ "sending" ], "summary": "Delete a sent copy", "description": "`DELETE /v1/sent/{message_id}` returns `202` with `id` and `status: \"deletion_pending\"`. Permanently deletes the sent copy and its attachments with no trash or undo. Deletion does not refund sending quota. Repeating DELETE is safe and can return `202` or `404`.", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "202": { "description": "Request accepted; inspect the response for its meaning.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "status": "deletion_pending", "message": "Example" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "operation_not_allowed", "internal_error" ] }, "patch": { "operationId": "updateSentMessageLabels", "tags": [ "labels" ], "summary": "Label a sent copy", "description": "Adds or removes labels on a saved outgoing message. The [individual label validation rules](https://cherami.to/docs/api/labels/update-message-labels) apply: a JSON body up to 20 KiB, at least one nonempty change array, and no name in both arrays after trimming. Labels are case-sensitive sets; duplicate names within an array are ignored.\n\nReturns `200` with the message ID and resulting labels. Additions and removals apply together without replacing unrelated labels. Repeating a change does not duplicate tags. Concurrent changes to different labels survive; opposite changes to the same label follow write order. Labels do not claim work for one agent.\n\nInvalid changes return `400 invalid_labels`. Missing, deleted or other-account messages return `404`. Updating labels requires neither sending nor deletion permission and consumes no sending allowance.", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResult" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "labels": [] } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "invalid_labels", "internal_error" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 20480 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelChange" }, "example": { "add_labels": [ "handled" ], "remove_labels": [ "needs-review" ] } } } }, "x-request-body-limit": 20480, "x-example-body": { "add_labels": [ "handled" ], "remove_labels": [ "needs-review" ] } }, "get": { "operationId": "getSentMessage", "tags": [ "sending" ], "summary": "Read a sent message", "description": "`GET /v1/sent/{message_id}` returns `200` with the sent metadata (without the list-only `preview`), top-level `reply_text`, and `submission`. `reply_text` is heuristic extraction, null if unavailable, or an empty string when no new text is detected. The original attributed bodies remain in `submission`.\n\nThe sender and recipient names are historical snapshots, not current inbox settings. Older full submissions may retain bare-address strings. Stored attachments contain original base64 bytes; source-derived inline files also include Content-ID relationships.\n\nMissing or other-account IDs return `404`; unavailable content can return `503`. An available sent copy is not evidence of delivery; inspect its status.", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentDetail" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 0, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": null, "in_reply_to": null, "labels": [], "reply_text": null, "submission": { "from": { "address": "my-agent@cherami.to" }, "to": [], "cc": [], "bcc": [], "subject": "Example", "text": "Example", "attachments": [] } } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`outbound_unavailable`: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "content_unavailable", "outbound_unavailable" ] } }, "/v1/messages/labels": { "patch": { "operationId": "bulkUpdateMessageLabels", "tags": [ "labels" ], "summary": "Label several received messages", "description": "Changes labels on an explicit set of received messages. The [individual label rules](https://cherami.to/docs/api/labels/update-message-labels) apply; the body may contain up to 32 KiB of JSON.\n\nSupply 1–100 message IDs in `message_ids`; duplicate IDs are updated once. Only `message_ids`, `add_labels`, and `remove_labels` are accepted. The same additions and removals apply to every target. IDs can belong to different inboxes owned by the account, but received and sent copies must use their respective endpoint.\n\nThe request is atomic: if any target is missing, deleted, or inaccessible, the response is a generic `404` and no labels change. Invalid ID arrays return `400 invalid_message_ids`. Success returns `200` with one result per distinct ID in request order.\n\nSelect explicit IDs before updating; this endpoint does not accept a filter. Larger jobs require separate batches, each atomic on its own. If a response is lost, the whole batch may have applied. Inspect current labels before retrying when other agents may be changing the same tags.", "parameters": [], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/LabelResult" } } }, "required": [ "messages" ] }, "example": { "messages": [] } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.\n\n`invalid_message_ids`: Supply 1–100 valid message IDs for a bulk label update.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "invalid_labels", "invalid_message_ids", "internal_error" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 32768 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLabelChange" }, "example": { "message_ids": [ "22222222-2222-4222-8222-222222222222" ], "add_labels": [ "handled" ] } } } }, "x-request-body-limit": 32768, "x-example-body": { "message_ids": [ "22222222-2222-4222-8222-222222222222" ], "add_labels": [ "handled" ] } } }, "/v1/sent/labels": { "patch": { "operationId": "bulkUpdateSentLabels", "tags": [ "labels" ], "summary": "Label several sent copies", "description": "Changes labels on an explicit set of saved outgoing copies. The [individual label rules](https://cherami.to/docs/api/labels/update-message-labels) apply; the body may contain up to 32 KiB of JSON.\n\nSupply 1–100 message IDs in `message_ids`; duplicate IDs are updated once. Only `message_ids`, `add_labels`, and `remove_labels` are accepted. The same additions and removals apply to every target. IDs can belong to different inboxes owned by the account, but received and sent copies must use their respective endpoint.\n\nThe request is atomic: if any target is missing, deleted, or inaccessible, the response is a generic `404` and no labels change. Invalid ID arrays return `400 invalid_message_ids`. Success returns `200` with one result per distinct ID in request order.\n\nSelect explicit IDs before updating; this endpoint does not accept a filter. Larger jobs require separate batches, each atomic on its own. If a response is lost, the whole batch may have applied. Inspect current labels before retrying when other agents may be changing the same tags.", "parameters": [], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/LabelResult" } } }, "required": [ "messages" ] }, "example": { "messages": [] } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.\n\n`invalid_message_ids`: Supply 1–100 valid message IDs for a bulk label update.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "invalid_labels", "invalid_message_ids", "internal_error" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 32768 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLabelChange" }, "example": { "message_ids": [ "22222222-2222-4222-8222-222222222222" ], "add_labels": [ "handled" ] } } } }, "x-request-body-limit": 32768, "x-example-body": { "message_ids": [ "22222222-2222-4222-8222-222222222222" ], "add_labels": [ "handled" ] } } }, "/v1/inboxes/{inbox_id}/labels": { "get": { "operationId": "listLabels", "tags": [ "labels" ], "summary": "Discover labels", "description": "`GET /v1/inboxes/{inbox_id}/labels` lists names currently used on undeleted received and sent copies in an owned, undeleted inbox.\n\nOptional `prefix` restricts names by a literal, case-sensitive prefix, trimmed using label-name rules. Empty or omitted means all names; supply it at most once. `limit` is 1–100, default 20. Results are ordered by name using case-sensitive binary order, not locale-specific collation. Continue with `cursor` and the same inbox and prefix.\n\nCounts describe messages, not conversations, and include all processing and sending states. A name disappears when no undeleted message uses it. There is no separate label registry or rename operation. Results and counts can change while you paginate.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Decimal integer without signs, whitespace or leading zeroes." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null." }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Literal case-sensitive prefix, trimmed, at most 128 UTF-8 bytes. Empty means all labels. Supply at most once." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelList" }, "example": { "labels": [], "next_cursor": null } } } }, "400": { "description": "`invalid_limit`: Use an integer from 1 to 100.\n\n`invalid_cursor`: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "invalid_limit", "invalid_cursor", "invalid_labels", "internal_error" ] } }, "/v1/inboxes/{inbox_id}/sent": { "post": { "operationId": "sendMessage", "tags": [ "sending" ], "summary": "Send a message", "description": "Follow [permitted sending](https://cherami.to/docs/guides/safety#permitted-sending).\n\nInspect the inbox’s [sending rules](https://cherami.to/docs/api/inboxes/get-sending-policy) before preparing a message. All send, reply, reply-all and forward paths enforce every To/Cc/Bcc destination. A new blocked attempt returns `403 recipient_not_allowed` without submission or quota use. An existing keyed attempt remains replayable after a policy edit, without resubmission.\n\nFor saved preparation and later submission, use the [draft API](https://cherami.to/docs/api/drafts). Draft sending uses the outcomes below, but the draft ID itself prevents another submission without expiry.\n\n### Request fields\n\nRecipient inputs are named mailbox objects, never bare strings or assembled header syntax. Names are display metadata, not identity verification; addresses determine delivery.\n\nThe owned inbox supplies From and its configured [sender name](https://cherami.to/docs/api/inboxes/update-inbox). Bcc addresses and names remain in the sender’s private saved copy but are not exposed in delivered recipient headers.\n\nAt most 50 combined To/Cc/Bcc entries are accepted. Unknown top-level and attachment fields are rejected. You cannot override From or supply arbitrary headers, remote attachment URLs, inline attachments, or raw MIME.\n\nJSON is limited to 8 MiB. The total email must fit the provider's 5 MiB limit, including generated MIME and attachments. Local size checks do not guarantee that generated MIME will fit.\n\nCherami appends “Sent via Cherami” to plain text and supplied HTML, after your body including quoted history. Do not add it yourself. Returned sent bodies include the attribution.\n\n### Reply targets\n\n`in_reply_to` is a resource ID, not an RFC Message-ID or thread ID. Received parents must be ready; sent parents must be accepted. Both need a usable Message-ID and must belong to the sending inbox. Cherami sets `In-Reply-To` and accumulated `References`, shortening long ancestry as needed.\n\nOn this explicit-send endpoint, supply recipients and subject yourself. For derived recipients and subject, use [reply](https://cherami.to/docs/api/sending/reply-message) or [reply-all](https://cherami.to/docs/api/sending/reply-all-message). There is no implicit latest-message selection. Unready, unaccepted, or headerless targets return `409`; missing, deleted, other-account, or other-inbox targets return `404`.\n\n### Response and outcomes\n\nA created sent resource returns `201` and `Location: /v1/sent/{id}`.\n\nInspect `message.status`, not just HTTP status: `accepted` means provider acceptance, not delivery; `rejected` means explicit pre-acceptance rejection; `unknown` means acceptance could not be confirmed. Accepted and unknown attempts retain their sending charge. A retry recovers the reserved attempt without resubmitting it.\n\n`provider_message_id`, `error_code`, `thread_id`, and `in_reply_to` can be null. `in_reply_to` identifies the Cherami parent resource when available.\n\nWhen `outcome_persisted` is false, the response reports a known provider outcome that could not be saved. Later reads may still say `unknown`; do not resend because of that mismatch. There is no automatic provider-submission retry or delivery/bounce tracking.\n\nIf a response is lost or an infrastructure error reports uncertainty, follow the same-key recovery contract below. Without a key, inspect sent messages before considering another send. Repeating an unkeyed POST can send a duplicate. An absent match in a short list alone is not proof that retrying is safe.\n\nProvider errors such as `E_RECIPIENT_SUPPRESSED`, `E_RATE_LIMIT_EXCEEDED`, or `E_DAILY_LIMIT_EXCEEDED` are reported as rejected sent outcomes, not necessarily HTTP errors. A suppressed recipient rejects the whole submission.\n\n### Retry a send with an idempotency key\n\nKeys are scoped to the authenticated account across HTTP and MCP, not to a connection or inbox. Protection lasts **24 hours from the first reserved attempt**, without renewal on retries. Keyed results include `replayed` and `idempotency_expires_at` (ISO timestamp). A new attempt returns `201` with `replayed: false`; a matching retry returns `200` with `replayed: true`, the original `message.id` and its current saved outcome. Both include `Location`. A replay adds no submission or quota charge.\n\nUse the same key, inbox and message fields for a retry. JSON property order does not matter; omitted and empty optional recipient/attachment arrays are equivalent. Recipient addresses, names and ordering, attachment ordering, body text, HTML, subject and reply target do matter. Address spelling is retained; changing its case changes the request fingerprint. Display names are trimmed, with omitted and blank names equivalent. Changes to the inbox’s configured sender name do not change a replay: the original submission retains the identity used at that time. Initial labels also matter, but their order and duplicates do not; omitted and empty label arrays are equivalent. Later label edits do not change the original retry input, and a replay does not reapply initial labels. Reusing an active key for different input returns `409 idempotency_conflict` without sending. Deleting the sent copy does not free its active key: a matching retry returns `409 idempotency_result_unavailable`. Ordinary access and inbox-ownership checks still apply.\n\nThe first request may still be running when a retry returns `unknown`. It may also have stopped before submitting or lost the provider's response. Cherami never resumes that reserved attempt on a retry. This prevents a second application submission but may leave an email unsent; it does not guarantee delivery or resolve uncertainty. Use `GET /v1/sent/{message_id}` to inspect it later. `outcome_persisted: true` on a replay describes the saved state being returned, not proof that it captures the provider's final outcome.\n\nValidation, authorization and quota failures before reservation do not consume the key. An uncertain infrastructure failure may have reserved it, so reuse the original key and unchanged payload to recover. Never generate a replacement key to bypass uncertainty. After expiry, the same key can create a new send: **do not retry an uncertain email after the window**. If the initial response was lost, measure the window conservatively from your first request time. A deliberately new email needs a new key.\n\nRequests without a key retain their existing behavior: every POST can create a separate send.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Matching replay: current resource or saved attempt, without another allocation or provider submission.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": true }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "replayed", "idempotency_expires_at" ] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": true, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": false } }, "required": [] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": false, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_message`: Correct the send fields, recipients, reply ID, or attachments using the message's guidance.\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.\n\n`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.\n\n`recipient_not_allowed`: The inbox’s sending rules block one or more recipients. Nothing was submitted or charged. Use allowed recipients or ask the human to review [Sending rules](https://cherami.to/account/sending-rules); do not bypass them through another inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`reply_not_ready`: A received reply or forward source must be ready; a sent source must have confirmed provider acceptance.\n\n`reply_headers_unavailable`: The target has no usable RFC Message-ID. Send a new message without `in_reply_to`.\n\n`idempotency_conflict`: The key belongs to different input. Recover with the original inbox and payload, not a replacement key.\n\n`idempotency_result_unavailable`: The key was used but its inbox, draft or sent copy is unavailable. No replacement was created or submitted; do not bypass protection with a new key.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.\n\n`message_too_large`: Reduce message content and attachments. Passing local checks does not guarantee generated MIME fits the provider limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`outbound_limit_reached`: Read `quota`, `reason` and `sufficient_capacity_at`. Waiting cannot fix `message_exceeds_allowance`; see [sending recovery](https://cherami.to/docs/api/sending/get-outbound-quota).", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay in seconds when supplied. Quota uses sufficient_capacity_at; absent when waiting cannot make the message fit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaError" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`outbound_unavailable`: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "reply_not_ready", "reply_headers_unavailable", "content_unavailable", "invalid_message", "invalid_name", "invalid_labels", "invalid_idempotency_key", "idempotency_conflict", "idempotency_result_unavailable", "operation_not_allowed", "recipient_not_allowed", "message_too_large", "outbound_limit_reached", "outbound_unavailable" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 8388608 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInput" }, "example": { "to": [ { "address": "recipient@example.com", "name": "Alex" } ], "subject": "Notes", "text": "Here are the notes.", "idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY" } } } }, "x-request-body-limit": 8388608, "x-example-body": { "to": [ { "address": "recipient@example.com", "name": "Alex" } ], "subject": "Notes", "text": "Here are the notes.", "idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY" } }, "get": { "operationId": "listSentMessages", "tags": [ "sending" ], "summary": "List sent messages", "description": "`GET /v1/inboxes/{inbox_id}/sent?limit=20` returns `200` with `{\"messages\":[...],\"next_cursor\":null}`.\n\nEach entry contains sent metadata plus `preview`, with the same [preview contract](https://cherami.to/docs/api/messages/list-messages) as received mail. All statuses are listed, newest-submitted first by default. Combine [search and filters](https://cherami.to/docs/guides/search) and choose `newest`, `oldest`, or `relevance` ordering. Limit is 1–100, default 20. Pass `next_cursor` as a URL-encoded `cursor` parameter on the same inbox's sent URL. Lists contain bounded previews, not full bodies or attachments. Use `labels_all` for required tags, optionally combined with `labels_any` and `labels_none`; keep the same filters with each cursor. See [label filtering](https://cherami.to/docs/guides/labels).", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Decimal integer without signs, whitespace or leading zeroes." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nonempty lexical subject/body search, at most 512 UTF-16 code units and 16 words or closed quoted phrases. Every term must match; no raw FTS operators. Attachments and filenames are excluded." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope." }, { "name": "recipient", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope." }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive literal substring, nonblank and at most 998 UTF-16 code units before trimming." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "description": "Inclusive lower service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "description": "Exclusive upper service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets." }, { "name": "labels_all", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Require every listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "labels_any", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Require at least one listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "labels_none", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Exclude any message carrying a listed label; unlabeled messages qualify. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "newest", "oldest", "relevance" ], "default": "newest" }, "description": "relevance requires query. Listings are live views, not snapshots." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/SentSummary" } }, "next_cursor": { "anyOf": [ { "type": "string", "description": "Opaque cursor; preserve resource, filters and order." }, { "type": "null" } ] } }, "required": [ "messages", "next_cursor" ] }, "example": { "messages": [], "next_cursor": null } } } }, "400": { "description": "`invalid_limit`: Use an integer from 1 to 100.\n\n`invalid_cursor`: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.\n\n`invalid_search`: Correct search terms, filters, timestamps, or ordering. See [search](https://cherami.to/docs/guides/search).\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`outbound_unavailable`: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "invalid_limit", "invalid_cursor", "invalid_search", "invalid_labels", "outbound_unavailable" ] } }, "/v1/inboxes/{inbox_id}/reply": { "post": { "operationId": "replyMessage", "tags": [ "sending" ], "summary": "Reply to a message", "description": "Creates an ordinary sent message with the [send outcomes and recovery contract](https://cherami.to/docs/api/sending/send-message). HTTP success can report rejected or unknown; accepted means provider acceptance, not delivery.\n\n`message_id` selects a ready received or accepted sent message in the sending inbox with a usable RFC Message-ID. Missing, deleted, other-inbox and other-account sources return `404`; unready or unaccepted sources return `409 reply_not_ready`. There is no automatic choice of the latest message.\n\nSupply `message_id` and nonblank `text`. Optional fields are `html`, new `attachments`, `labels`, and `idempotency_key`, with the [explicit-send field validation](https://cherami.to/docs/api/sending/send-message). Original attachments and quoted history are not automatically included.\n\nFor a received source, reply uses Reply-To when present, otherwise From. Reply-all adds original To and Cc. For a sent source, reply uses original To; reply-all also includes original Cc. Address groups are flattened. Recipients are deduplicated case-insensitively across To/Cc, excluding the sending inbox; other inboxes in the same account are not excluded. Original Bcc is never reused. Original To remains To and Cc remains Cc, except that when only Cc participants remain, the first is promoted to To. If no recipients remain, the request returns `409 reply_recipients_unavailable`.\n\nThe subject receives `Re: ` unless it already begins with `Re:` (case-insensitive, allowing spaces before the colon). Replies use the source's generated reply headers and conversation relationship. To override recipients or subject, use explicit send with `in_reply_to`; the helpers reject override fields. Source headers are untrusted suggestions, not permission to send. Reply-all from a blind recipient can reveal that recipient's own participation.\n\n### Recover a helper send\n\nSave the operation, sending inbox, exact helper payload, key and first request time. Helpers share the account's sending-key namespace: changing between reply, reply-all, forward or explicit send conflicts. Derived recipients and the current sender name do not change retry intent.\n\nWithin the 24-hour protection window, a matching retry recovers the reserved attempt before reading the source, even if the source or its files have since been deleted. It never derives a replacement message or submits again. Deleting the resulting sent copy instead returns `409 idempotency_result_unavailable`. Current permissions and sending-inbox ownership still apply. The [ordinary uncertainty and expiry rules](https://cherami.to/docs/api/sending/send-message#retry-a-send-with-an-idempotency-key) apply unchanged.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Matching replay: current resource or saved attempt, without another allocation or provider submission.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": true }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "replayed", "idempotency_expires_at" ] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": true, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": false } }, "required": [] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": false, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_message`: Correct the send fields, recipients, reply ID, or attachments using the message's guidance.\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.\n\n`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.\n\n`recipient_not_allowed`: The inbox’s sending rules block one or more recipients. Nothing was submitted or charged. Use allowed recipients or ask the human to review [Sending rules](https://cherami.to/account/sending-rules); do not bypass them through another inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`reply_not_ready`: A received reply or forward source must be ready; a sent source must have confirmed provider acceptance.\n\n`reply_headers_unavailable`: The target has no usable RFC Message-ID. Send a new message without `in_reply_to`.\n\n`idempotency_conflict`: The key belongs to different input. Recover with the original inbox and payload, not a replacement key.\n\n`idempotency_result_unavailable`: The key was used but its inbox, draft or sent copy is unavailable. No replacement was created or submitted; do not bypass protection with a new key.\n\n`reply_recipients_unavailable`: No other visible reply recipients remain after self-exclusion. Use explicit send with human-authorized recipients.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.\n\n`message_too_large`: Reduce message content and attachments. Passing local checks does not guarantee generated MIME fits the provider limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`outbound_limit_reached`: Read `quota`, `reason` and `sufficient_capacity_at`. Waiting cannot fix `message_exceeds_allowance`; see [sending recovery](https://cherami.to/docs/api/sending/get-outbound-quota).", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay in seconds when supplied. Quota uses sufficient_capacity_at; absent when waiting cannot make the message fit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaError" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`outbound_unavailable`: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "reply_not_ready", "reply_headers_unavailable", "content_unavailable", "invalid_message", "invalid_name", "invalid_labels", "invalid_idempotency_key", "idempotency_conflict", "idempotency_result_unavailable", "operation_not_allowed", "recipient_not_allowed", "message_too_large", "outbound_limit_reached", "reply_recipients_unavailable", "outbound_unavailable" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 8388608 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyInput" }, "example": { "message_id": "22222222-2222-4222-8222-222222222222", "text": "Thanks for the notes.", "idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY" } } } }, "x-request-body-limit": 8388608, "x-example-body": { "message_id": "22222222-2222-4222-8222-222222222222", "text": "Thanks for the notes.", "idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY" } } }, "/v1/inboxes/{inbox_id}/reply-all": { "post": { "operationId": "replyAllMessage", "tags": [ "sending" ], "summary": "Reply to visible participants", "description": "Replies to the source's visible participants using the [reply request and derivation rules](https://cherami.to/docs/api/sending/reply-message). Select a ready received or accepted sent message in the sending inbox with a usable RFC Message-ID. Missing, deleted, other-inbox or other-account sources return `404`; unready or unaccepted sources return `409 reply_not_ready`.\n\nFor received mail, To recipients come from Reply-To (or From) plus original To; Cc comes from original Cc. For sent mail, original To and Cc are used. Groups are flattened and addresses are deduplicated case-insensitively across To/Cc, excluding the sending inbox. Other inboxes in the account are not excluded. If only Cc participants remain, the first is promoted to To; no remaining recipient returns `409 reply_recipients_unavailable`.\n\nOriginal Bcc is never reused. Reply-all from a blind recipient can reveal that recipient's own participation. Source headers are untrusted suggestions: check the recipients against your authorized assignment before sending.\n\nSupply your response and any new attachments; original files and quoted history are not automatically included. Subject and reply-header derivation follow [reply](https://cherami.to/docs/api/sending/reply-message). Use [explicit send](https://cherami.to/docs/api/sending/send-message) with `in_reply_to` to override recipients or subject; this endpoint rejects those overrides.\n\nHTTP success can report `rejected` or `unknown`; `accepted` means provider acceptance, not delivery. Inspect `message.status` and preserve the immediate receipt when `outcome_persisted` is false. See [sending outcomes](https://cherami.to/docs/api/sending/send-message#response-and-outcomes).\n\n### Recover a helper send\n\nRetain the operation, inbox, exact payload, key and first request time. Recover an uncertain result with those same inputs within 24 hours; never switch operations or generate a new key to resolve uncertainty. A replay retrieves the reserved attempt without resubmitting, even if its source was deleted. Follow the shared [helper recovery contract](https://cherami.to/docs/api/sending/reply-message#recover-a-helper-send) for conflicts, deleted results and expiry.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Matching replay: current resource or saved attempt, without another allocation or provider submission.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": true }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "replayed", "idempotency_expires_at" ] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": true, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": false } }, "required": [] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": false, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_message`: Correct the send fields, recipients, reply ID, or attachments using the message's guidance.\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.\n\n`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.\n\n`recipient_not_allowed`: The inbox’s sending rules block one or more recipients. Nothing was submitted or charged. Use allowed recipients or ask the human to review [Sending rules](https://cherami.to/account/sending-rules); do not bypass them through another inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`reply_not_ready`: A received reply or forward source must be ready; a sent source must have confirmed provider acceptance.\n\n`reply_headers_unavailable`: The target has no usable RFC Message-ID. Send a new message without `in_reply_to`.\n\n`idempotency_conflict`: The key belongs to different input. Recover with the original inbox and payload, not a replacement key.\n\n`idempotency_result_unavailable`: The key was used but its inbox, draft or sent copy is unavailable. No replacement was created or submitted; do not bypass protection with a new key.\n\n`reply_recipients_unavailable`: No other visible reply recipients remain after self-exclusion. Use explicit send with human-authorized recipients.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.\n\n`message_too_large`: Reduce message content and attachments. Passing local checks does not guarantee generated MIME fits the provider limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`outbound_limit_reached`: Read `quota`, `reason` and `sufficient_capacity_at`. Waiting cannot fix `message_exceeds_allowance`; see [sending recovery](https://cherami.to/docs/api/sending/get-outbound-quota).", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay in seconds when supplied. Quota uses sufficient_capacity_at; absent when waiting cannot make the message fit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaError" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`outbound_unavailable`: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "reply_not_ready", "reply_headers_unavailable", "content_unavailable", "invalid_message", "invalid_name", "invalid_labels", "invalid_idempotency_key", "idempotency_conflict", "idempotency_result_unavailable", "operation_not_allowed", "recipient_not_allowed", "message_too_large", "outbound_limit_reached", "reply_recipients_unavailable", "outbound_unavailable" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 8388608 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyInput" }, "example": { "message_id": "22222222-2222-4222-8222-222222222222", "text": "Thanks for the notes.", "idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY" } } } }, "x-request-body-limit": 8388608, "x-example-body": { "message_id": "22222222-2222-4222-8222-222222222222", "text": "Thanks for the notes.", "idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY" } } }, "/v1/inboxes/{inbox_id}/forward": { "post": { "operationId": "forwardMessage", "tags": [ "sending" ], "summary": "Forward a message", "description": "Creates an ordinary sent message with the [send outcomes and recovery contract](https://cherami.to/docs/api/sending/send-message). HTTP success can report rejected or unknown; accepted means provider acceptance, not delivery.\n\n`message_id` selects a ready received or accepted sent message in the sending inbox. Missing, deleted, other-inbox and other-account sources return `404`; unready or unaccepted sources return `409 reply_not_ready`. A forward does not require an RFC Message-ID.\n\nSupply `message_id` and nonempty `to`. Optional fields are `cc`, `bcc`, plain-text `note`, boolean `include_attachments` (default `true`), `labels`, and `idempotency_key`. Recipient, label and size limits are the same as explicit send. Forward recipients are explicit and are not automatically deduplicated.\n\nThe subject receives `Fwd: ` unless it already starts with `Fw:` or `Fwd:`. The note precedes a forwarded header block containing From, available Date, Subject, To and Cc, never Bcc. Original text and HTML are retained, including quoted history and earlier attribution. HTML-only originals get a non-rendered plain-text alternative. A forward has no reply parent or inherited reply headers and starts a new Cherami conversation.\n\nAttachments are included by default with their original bytes; embedded images retain their Content-ID relationships. Unsafe or missing filenames get safe transport names. Unusable MIME types become `application/octet-stream`. Setting `include_attachments: false` excludes all original files, including embedded images, so images referenced by the HTML may be unavailable. No attachment is silently removed to fit a limit. Missing expected content returns `503 content_unavailable`; oversized forwards return `413 message_too_large`, or a provider rejection if generated MIME exceeds its limit. An unusable original inline Content-ID returns `400 invalid_message`. Retrieve the original later for unavailable content; explicitly exclude attachments or use an explicit send for a deliberately reduced message.\n\nExcluding Bcc from generated headers does not redact anything already written in the original body. Review the original content before authorizing disclosure.\n\n### Recover a helper send\n\nSave the operation, sending inbox, exact helper payload, key and first request time. Helpers share the account's sending-key namespace: changing between reply, reply-all, forward or explicit send conflicts. Omitted `include_attachments` and `true` are equivalent; omitted and empty notes are equivalent. Derived recipients, bodies and the current sender name do not change retry intent.\n\nWithin the 24-hour protection window, a matching retry recovers the reserved attempt before reading the source, even if the source or its files have since been deleted. It never derives a replacement message or submits again. Deleting the resulting sent copy instead returns `409 idempotency_result_unavailable`. Current permissions and sending-inbox ownership still apply. The [ordinary uncertainty and expiry rules](https://cherami.to/docs/api/sending/send-message#retry-a-send-with-an-idempotency-key) apply unchanged.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Matching replay: current resource or saved attempt, without another allocation or provider submission.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": true }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "replayed", "idempotency_expires_at" ] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": true, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": false } }, "required": [] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": false, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_message`: Correct the send fields, recipients, reply ID, or attachments using the message's guidance.\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.\n\n`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.\n\n`recipient_not_allowed`: The inbox’s sending rules block one or more recipients. Nothing was submitted or charged. Use allowed recipients or ask the human to review [Sending rules](https://cherami.to/account/sending-rules); do not bypass them through another inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`reply_not_ready`: A received reply or forward source must be ready; a sent source must have confirmed provider acceptance.\n\n`idempotency_conflict`: The key belongs to different input. Recover with the original inbox and payload, not a replacement key.\n\n`idempotency_result_unavailable`: The key was used but its inbox, draft or sent copy is unavailable. No replacement was created or submitted; do not bypass protection with a new key.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.\n\n`message_too_large`: Reduce message content and attachments. Passing local checks does not guarantee generated MIME fits the provider limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`outbound_limit_reached`: Read `quota`, `reason` and `sufficient_capacity_at`. Waiting cannot fix `message_exceeds_allowance`; see [sending recovery](https://cherami.to/docs/api/sending/get-outbound-quota).", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay in seconds when supplied. Quota uses sufficient_capacity_at; absent when waiting cannot make the message fit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaError" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`outbound_unavailable`: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "reply_not_ready", "content_unavailable", "invalid_message", "invalid_name", "invalid_labels", "invalid_idempotency_key", "idempotency_conflict", "idempotency_result_unavailable", "operation_not_allowed", "recipient_not_allowed", "message_too_large", "outbound_limit_reached", "outbound_unavailable" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 8388608 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardInput" }, "example": { "message_id": "22222222-2222-4222-8222-222222222222", "to": [ { "address": "recipient@example.com" } ], "note": "For your review.", "idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY" } } } }, "x-request-body-limit": 8388608, "x-example-body": { "message_id": "22222222-2222-4222-8222-222222222222", "to": [ { "address": "recipient@example.com" } ], "note": "For your review.", "idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY" } } }, "/v1/outbound/quota": { "get": { "operationId": "getOutboundQuota", "tags": [ "sending" ], "summary": "Read sending allowance", "description": "Returns the current account-wide sending allowance.\n\nEvery To/Cc/Bcc entry costs one, including repeats. All inboxes share this allowance. Accepted and unknown submissions count; rejected submissions do not when the outcome is saved. Later bounces and message or inbox deletion do not refund charges.\n\nSending with insufficient capacity returns `429` with `error.code: \"outbound_limit_reached\"`, an actionable `error.message`, `quota` containing the allowance fields, and the capacity details in the response schema.\n\n`Retry-After` is supplied from `sufficient_capacity_at`, not the first charge expiry. No `Retry-After` is supplied when the message exceeds the entire account allowance: waiting cannot fix that. A concurrent release can make the returned snapshot already sufficient even though the earlier check blocked the request. Neither an estimate nor available Cherami capacity guarantees provider acceptance.\n\nA quota-blocked send does not submit a message. It does not override recovery rules for an earlier uncertain attempt. Receiving, reading, organizing mail, saving drafts and feedback remain available when sending allowance runs out. Request inbox or sending increases through [feedback](https://cherami.to/docs/api/feedback) or hello@cherami.to; requests are reviewed manually. [Allowance policy](https://cherami.to/pricing).", "parameters": [], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quota" }, "example": { "allowance": 25, "used": 0, "remaining": 25, "next_capacity_at": null, "next_capacity_amount": 0, "window_hours": 24, "unit": "recipient_deliveries", "increase_request": "Describe your workflow and desired capacity in feedback or email hello@cherami.to.", "policy_url": "https://cherami.to/pricing" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`outbound_unavailable`: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "outbound_unavailable" ] } }, "/v1/inboxes/{inbox_id}/drafts": { "post": { "operationId": "createDraft", "tags": [ "drafts" ], "summary": "Create a draft", "description": "Drafts belong to one owned inbox. Saving or editing consumes no sending allowance and does not require sending permission. Sending requires current permission, recipient-policy approval and available allowance; deletion requires deletion permission.\n\nThe body can be `{}` for an empty draft. Supply any of `to`, `cc`, `bcc`, `subject`, `text`, `html`, `attachments`, `in_reply_to` and `labels`, using the [sending field formats and limits](https://cherami.to/docs/api/sending/send-message). Recipients, subject and text may be missing or empty until sending. Unknown fields are rejected. Creation and edit JSON may be up to 8 MiB; saved content uses the same 5 MiB local bound, 50 recipients and 32 attachments as outgoing mail. Sending also checks current limits, including the provider's generated MIME limit.\n\n`html` and `in_reply_to` additionally accept null to clear. Empty arrays clear recipient lists, attachments or initial sent-copy labels. Recipient display names are preserved. Supplied attachments are padded base64 original bytes, not URLs.\n\nOptional `idempotency_key` protects creation. It accepts 1–128 ASCII letters, digits, hyphens or underscores. Keep it with the original payload and first request time; follow the creation-recovery guidance on this page.\n\nNew creation returns `201`, `Location: /v1/drafts/{id}` and metadata.\n\nThe `replayed` and `idempotency_expires_at` fields appear only for keyed creation. Creation returns metadata, not the full body; retrieve the draft to inspect saved content.\n\n### Prepare a reply or forward\n\nCreation also accepts `source`.\n\n`source.action` is `reply`, `reply-all` or `forward`. `message_id` must identify a ready received or accepted sent message in the same inbox. The [ordinary correspondence derivation rules](https://cherami.to/docs/api/sending/reply-message) apply: reply recipients exclude self and original Bcc; forwards retain original bodies rather than extracted reply text.\n\nReplies save derived recipients, subject and `in_reply_to`, with your supplied response and new attachments. No original history or files are automatically copied. Explicit fields override derived fields, including empty arrays or a null reply target. The reply target must remain available and usable when the draft is sent; changing `in_reply_to` later does not rederive recipients or subject.\n\nFor forwards, `text` on creation is the introductory note. Supply recipients explicitly, or add them later. The saved text and HTML contain the full forward. `source.include_attachments` defaults to true and is valid only for forwards; false excludes all original files, including embedded images. Creation with a forward source cannot also supply `attachments`; edit afterward to replace the saved file list. Original bytes and usable inline Content-ID relationships are retained. Missing or oversized included files fail rather than being silently omitted. Forwarding does not redact private information already in the body.\n\nPreparation happens once, before the draft is returned. Sending does not regenerate recipients, forward content or attachments from the source. A prepared forward remains usable if its source is subsequently deleted. A source is a preparation instruction on creation, not an editable field.\n\n### Recover creation\n\nCreation keys are account-scoped across HTTP and MCP, in a namespace separate from inbox creation and sending. Protection lasts **24 hours from creation**, without renewal. A matching retry returns `200`, `replayed: true` and the original draft's **current metadata**, including later edits or submission state. It never reapplies the creation payload. A changed payload returns `409 idempotency_conflict`.\n\nThe comparison uses normalized creation intent: omitted/empty arrays, trimmed display names, normalized label sets and missing/empty subject or text are equivalent. Content and recipient/file order remain significant. With a source, explicitly supplied fields are also significant because they override derived values; preserve the original payload. Default and explicit true attachment inclusion are equivalent.\n\nDeleting the draft does not release an active key. A matching retry returns `409 idempotency_result_unavailable`, without creating a replacement. Replay does not require reloading a preparation source that has since disappeared. Access and inbox ownership still apply.\n\nIf creation cannot be confirmed, retry only with the original key and payload within a conservatively measured 24 hours of the first request. Without a key or after expiry, list drafts with `state=all` and reconcile before creating anything else. Unlike an inbox address, draft content is not unique: blindly recreating can allocate a duplicate. A missing entry in one page does not establish that creation failed.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Matching replay: current resource or saved attempt, without another allocation or provider submission.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreatedDraft" }, { "type": "object", "properties": { "replayed": { "const": true }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "replayed", "idempotency_expires_at" ] } ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "state": "draft", "subject": "Example", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "sent_message_id": null, "replayed": true, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreatedDraft" }, { "type": "object", "properties": { "replayed": { "const": false } }, "required": [] } ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "state": "draft", "subject": "Example", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "sent_message_id": null, "replayed": false, "idempotency_expires_at": "2026-10-02T00:00:00.000Z" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_draft`: Use supported draft fields, source preparation or listing parameters. Draft cursors that are malformed or do not match the inbox/state also use this code.\n\n`invalid_message`: Correct the send fields, recipients, reply ID, or attachments using the message's guidance.\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.\n\n`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_conflict`: The key belongs to different input. Recover with the original inbox and payload, not a replacement key.\n\n`idempotency_result_unavailable`: The key was used but its inbox, draft or sent copy is unavailable. No replacement was created or submitted; do not bypass protection with a new key.\n\n`reply_not_ready`: A received reply or forward source must be ready; a sent source must have confirmed provider acceptance.\n\n`reply_recipients_unavailable`: No other visible reply recipients remain after self-exclusion. Use explicit send with human-authorized recipients.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.\n\n`message_too_large`: Reduce message content and attachments. Passing local checks does not guarantee generated MIME fits the provider limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`draft_unavailable`: Draft operation is uncertain. Follow [draft-specific recovery](https://cherami.to/docs/api/drafts); do not blindly create a replacement.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "invalid_draft", "invalid_message", "invalid_name", "invalid_labels", "invalid_idempotency_key", "idempotency_conflict", "idempotency_result_unavailable", "message_too_large", "not_found", "reply_not_ready", "content_unavailable", "reply_recipients_unavailable", "draft_unavailable" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 8388608 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraft" }, "example": { "subject": "Proposal for review", "text": "Draft proposal.", "idempotency_key": "RETAIN_A_UNIQUE_CREATION_KEY" } } } }, "x-request-body-limit": 8388608, "x-example-body": { "subject": "Proposal for review", "text": "Draft proposal.", "idempotency_key": "RETAIN_A_UNIQUE_CREATION_KEY" } }, "get": { "operationId": "listDrafts", "tags": [ "drafts" ], "summary": "List drafts", "description": "Returns `200` with `{\"drafts\":[...],\"next_cursor\":null}`. Entries contain draft metadata without creation-key fields. `state` is `draft` (default), `submitted` or `all`. Results are newest-created first. `limit` is 1–100, default 20; use the returned opaque `cursor` with the same inbox and state. This is a live listing, not a snapshot. Drafts do not appear in received/sent mail search or conversations before submission.\n\nUnsupported or repeated query parameters and malformed or mismatched cursors return `400 invalid_draft`; an invalid limit returns `400 invalid_limit`.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Decimal integer without signs, whitespace or leading zeroes." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "submitted", "all" ], "default": "draft" }, "description": "Include submitted drafts when reconciling uncertain creation. Only limit, cursor and state are accepted, each once." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "$ref": "#/components/schemas/DraftMetadata" } }, "next_cursor": { "anyOf": [ { "type": "string", "description": "Opaque cursor; preserve resource, filters and order." }, { "type": "null" } ] } }, "required": [ "drafts", "next_cursor" ] }, "example": { "drafts": [], "next_cursor": null } } } }, "400": { "description": "`invalid_limit`: Use an integer from 1 to 100.\n\n`invalid_draft`: Use supported draft fields, source preparation or listing parameters. Draft cursors that are malformed or do not match the inbox/state also use this code.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`draft_unavailable`: Draft operation is uncertain. Follow [draft-specific recovery](https://cherami.to/docs/api/drafts); do not blindly create a replacement.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "invalid_limit", "invalid_draft", "draft_unavailable" ] } }, "/v1/drafts/{draft_id}": { "get": { "operationId": "getDraft", "tags": [ "drafts" ], "summary": "Retrieve a draft", "description": "Returns metadata plus `from` and `content`. `from` is the inbox's **current** address and optional sender name. `content` contains full `to`, `cc`, `bcc`, `subject`, `text`, `attachments`, optional `html`, `in_reply_to` and nonempty `labels`. Attachment objects include `filename`, `type`, base64 `content`, and `disposition`; source-derived inline files also have `contentId`. Bodies are not extracted or truncated.\n\nThe content is the saved draft, before Cherami's outgoing attribution. Sending uses current sender settings and appends attribution then. For a submitted draft, retrieve `sent_message_id` through the [sent-message endpoint](https://cherami.to/docs/api/sending/get-sent-message) for the actual sender snapshot, attributed content and outcome. Draft retrieval alone is not approval and does not lock the content.", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDetail" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "state": "draft", "subject": "Example", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "sent_message_id": null, "from": { "address": "my-agent@cherami.to" }, "content": { "to": [], "cc": [], "bcc": [], "subject": "Example", "text": "Example", "attachments": [] } } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`draft_unavailable`: Draft operation is uncertain. Follow [draft-specific recovery](https://cherami.to/docs/api/drafts); do not blindly create a replacement.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "content_unavailable", "draft_unavailable" ] }, "patch": { "operationId": "updateDraft", "tags": [ "drafts" ], "summary": "Edit a draft", "description": "Supply at least one editable creation field, excluding `source` and `idempotency_key`. Only supplied fields change. Recipient arrays, attachments and labels replace their entire respective lists. When revising `text`, revise or clear `html` separately if needed; Cherami does not synchronize the alternatives. New attachment inputs use the ordinary three-field format, not service-generated inline metadata.\n\nSuccessful edits return `200` with draft metadata. Concurrent edits to different fields preserve both changes; the last saved value wins for the same field. No version parameter or review lock is supported. Repeated contention can return `409 draft_busy`; retrieve current content before editing again. After an uncertain acknowledgement, also retrieve before repeating an edit that might overwrite another agent's work.\n\nSubmitted drafts return `409 draft_submitted` and cannot be edited or returned to draft.", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMetadata" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "state": "draft", "subject": "Example", "created_at": "2026-10-01T00:00:00.000Z", "updated_at": "2026-10-01T00:00:00.000Z", "sent_message_id": null } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_draft`: Use supported draft fields, source preparation or listing parameters. Draft cursors that are malformed or do not match the inbox/state also use this code.\n\n`invalid_message`: Correct the send fields, recipients, reply ID, or attachments using the message's guidance.\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`draft_busy`: An edit/send raced other changes. Retrieve current content before trying again.\n\n`draft_submitted`: Submitted drafts cannot be edited or returned to draft. Retrieve the linked sent message.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.\n\n`message_too_large`: Reduce message content and attachments. Passing local checks does not guarantee generated MIME fits the provider limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`draft_unavailable`: Draft operation is uncertain. Follow [draft-specific recovery](https://cherami.to/docs/api/drafts); do not blindly create a replacement.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "invalid_draft", "invalid_message", "invalid_name", "invalid_labels", "message_too_large", "draft_busy", "draft_submitted", "content_unavailable", "draft_unavailable" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 8388608 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDraft" }, "example": { "text": "Revised proposal.", "html": null } } } }, "x-request-body-limit": 8388608, "x-example-body": { "text": "Revised proposal.", "html": null } }, "delete": { "operationId": "deleteDraft", "tags": [ "drafts" ], "summary": "Delete a draft", "description": "`DELETE /v1/drafts/{draft_id}` returns `202` with `id`, `status: \"deletion_pending\"` and a message. It permanently removes the draft and its attachments, with no undo. A linked sent copy is separate: deleting either does not delete the other. Repeating deletion is safe and can return `202` or `404`. Inbox deletion covers both drafts and sent copies.", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "202": { "description": "Request accepted; inspect the response for its meaning.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedDraft" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "status": "deletion_pending", "message": "Example" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`draft_unavailable`: Draft operation is uncertain. Follow [draft-specific recovery](https://cherami.to/docs/api/drafts); do not blindly create a replacement.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "operation_not_allowed", "draft_unavailable" ] } }, "/v1/drafts/{draft_id}/send": { "post": { "operationId": "sendDraft", "tags": [ "drafts" ], "summary": "Send a draft", "description": "`POST /v1/drafts/{draft_id}/send` with `{}` or `{\"idempotency_key\":\"YOUR_SEND_KEY\"}`.\n\nSending takes the current saved content, not a previously retrieved copy. The draft freezes as `submitted` when an outgoing attempt is reserved, with `sent_message_id` identifying that attempt. An edit that wins before reservation must be included or cause `409 draft_busy`; a send never silently submits an older saved copy. Concurrent sends cannot reserve multiple submissions for the same draft.\n\nValidation, ownership, permission, recipient-policy or quota failures before reservation leave it editable. After reservation it remains submitted for **every** provider outcome, including rejection and uncertainty. There is no automatic retry or return-to-draft operation. A deliberately new attempt requires a new draft; do not create one merely to resolve an unknown outcome.\n\nThe response uses the [ordinary send receipt and outcomes](https://cherami.to/docs/api/sending/send-message): `201` for a new attempt, `200` with `replayed: true` when recovering. `Location` points to `/v1/sent/{sent_message_id}`. Acceptance is not proof of delivery. If `outcome_persisted` is false, retain the stronger immediate outcome even if later reads lag.\n\n**The draft ID itself prevents another submission, without expiry.** Repeat the same send request to recover an uncertain attempt, not to restart it. This can preserve a possibly unsent attempt rather than risk a duplicate. Deleting the sent copy does not unlock the draft; recovery then returns `409 draft_result_unavailable` (or `idempotency_result_unavailable` for an active sending key).\n\nOptional sending keys share the ordinary account-scoped sending namespace and 24-hour lifetime. Their intent identifies this draft, not its mutable fields. Changing the draft ID or reusing a key from an ordinary send conflicts. Key expiry does not remove the draft's permanent submitted state. A replay recovered through the draft association need not include `idempotency_expires_at`; it does not allocate or renew a key.", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Matching replay: current resource or saved attempt, without another allocation or provider submission.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": true } }, "required": [ "replayed" ] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true, "replayed": true } } } }, "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Location": { "description": "Relative URL of the resulting resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendReceipt" }, { "type": "object", "properties": { "replayed": { "const": false } }, "required": [] } ] }, "example": { "limited": false, "message": { "id": "33333333-3333-4333-8333-333333333333", "inbox_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-01T00:00:00.000Z", "recipient_count": 1, "status": "unknown", "provider_message_id": null, "error_code": null, "thread_id": "44444444-4444-4444-8444-444444444444", "in_reply_to": null, "labels": [] }, "outcome_persisted": true } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_message`: Correct the send fields, recipients, reply ID, or attachments using the message's guidance.\n\n`invalid_name`: Correct the inbox, sender or recipient display name using the returned guidance.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.\n\n`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.\n\n`invalid_draft`: Use supported draft fields, source preparation or listing parameters. Draft cursors that are malformed or do not match the inbox/state also use this code.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.\n\n`recipient_not_allowed`: The inbox’s sending rules block one or more recipients. Nothing was submitted or charged. Use allowed recipients or ask the human to review [Sending rules](https://cherami.to/account/sending-rules); do not bypass them through another inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`reply_not_ready`: A received reply or forward source must be ready; a sent source must have confirmed provider acceptance.\n\n`reply_headers_unavailable`: The target has no usable RFC Message-ID. Send a new message without `in_reply_to`.\n\n`idempotency_conflict`: The key belongs to different input. Recover with the original inbox and payload, not a replacement key.\n\n`idempotency_result_unavailable`: The key was used but its inbox, draft or sent copy is unavailable. No replacement was created or submitted; do not bypass protection with a new key.\n\n`draft_busy`: An edit/send raced other changes. Retrieve current content before trying again.\n\n`draft_result_unavailable`: The draft was already submitted but its sent copy is unavailable. Nothing was resubmitted.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.\n\n`message_too_large`: Reduce message content and attachments. Passing local checks does not guarantee generated MIME fits the provider limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`outbound_limit_reached`: Read `quota`, `reason` and `sufficient_capacity_at`. Waiting cannot fix `message_exceeds_allowance`; see [sending recovery](https://cherami.to/docs/api/sending/get-outbound-quota).", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay in seconds when supplied. Quota uses sufficient_capacity_at; absent when waiting cannot make the message fit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaError" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.\n\n`draft_unavailable`: Draft operation is uncertain. Follow [draft-specific recovery](https://cherami.to/docs/api/drafts); do not blindly create a replacement.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "reply_not_ready", "reply_headers_unavailable", "content_unavailable", "invalid_message", "invalid_name", "invalid_labels", "invalid_idempotency_key", "idempotency_conflict", "idempotency_result_unavailable", "operation_not_allowed", "recipient_not_allowed", "message_too_large", "outbound_limit_reached", "invalid_draft", "draft_busy", "draft_result_unavailable", "draft_unavailable" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 4096 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendDraft" }, "example": {} } } }, "x-request-body-limit": 4096, "x-example-body": {} } }, "/v1/inboxes/{inbox_id}/threads": { "get": { "operationId": "listThreads", "tags": [ "threads" ], "summary": "List conversations", "description": "Threads are grouped automatically. They contain ready received messages and sent attempts, including rejected and unknown outcomes.\n\n`GET /v1/inboxes/{inbox_id}/threads?limit=20` returns `200`.\n\nMost recent activity first by default. Accepts the shared [search, filters and ordering](https://cherami.to/docs/guides/search). A conversation matches when one member satisfies every condition. Filtered results additionally include `matching_message_ids` (up to 100, newest first) and `matching_message_count` (total matching members). `subject` is from the earliest surviving message and can be null. Counts include attempts, not just successful correspondence.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Decimal integer without signs, whitespace or leading zeroes." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nonempty lexical subject/body search, at most 512 UTF-16 code units and 16 words or closed quoted phrases. Every term must match; no raw FTS operators. Attachments and filenames are excluded." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope." }, { "name": "recipient", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope." }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive literal substring, nonblank and at most 998 UTF-16 code units before trimming." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "description": "Inclusive lower service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "description": "Exclusive upper service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets." }, { "name": "labels_all", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Require every listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "labels_any", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Require at least one listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "labels_none", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32 }, "description": "Exclude any message carrying a listed label; unlabeled messages qualify. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope.", "style": "form", "explode": true }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "newest", "oldest", "relevance" ], "default": "newest" }, "description": "relevance requires query. Listings are live views, not snapshots." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadSummary" } }, "next_cursor": { "anyOf": [ { "type": "string", "description": "Opaque cursor; preserve resource, filters and order." }, { "type": "null" } ] } }, "required": [ "threads", "next_cursor" ] }, "example": { "threads": [], "next_cursor": null } } } }, "400": { "description": "`invalid_limit`: Use an integer from 1 to 100.\n\n`invalid_cursor`: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.\n\n`invalid_search`: Correct search terms, filters, timestamps, or ordering. See [search](https://cherami.to/docs/guides/search).\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "invalid_limit", "invalid_cursor", "invalid_search", "invalid_labels", "internal_error" ] } }, "/v1/threads/{thread_id}": { "get": { "operationId": "getThread", "tags": [ "threads" ], "summary": "Read a conversation", "description": "`GET /v1/threads/{thread_id}?limit=20` returns `200` with conversation metadata, plus `messages` and `next_cursor`.\n\nEach entry has `direction` (`received` or `sent`), `timestamp` (ISO service receipt/submission time), and the fields from [received detail](https://cherami.to/docs/api/messages/get-message) or [sent detail](https://cherami.to/docs/api/sending/get-sent-message).\n\nBodies and attachment metadata are included, without attachment bytes. Received attachments use the ordinary download endpoint. Sent thread attachments have `id`, `filename`, `mime_type`, and `size` in bytes; use ordinary sent detail for their base64 content.\n\nThe first page contains the newest messages, **chronological within the page**. The next page contains older messages. Metadata counts describe the conversation, not just the current page.\n\nAccepts `limit` 1–100, default 20. Follow `next_cursor` as a URL-encoded `cursor` parameter on the same resource URL. Ordering uses service timestamps, not sender-controlled Date headers.\n\nConversations can update, and pages are not a snapshot. Previously returned thread IDs remain usable while their conversation exists; the returned `id` may differ from the requested one. Continue a pagination sequence on the same requested URL, and refetch recent context when needed.\n\nPending, processing, and failed received messages have `thread_id: null` and are absent from threads. They remain available through message endpoints. Deleted messages disappear; surviving messages remain grouped. Empty, missing, or other-account conversations return `404`. Invalid limits/cursors return `400`, and unavailable content can return `503`.\n\nEach message retains its own `labels`; threads have no label set. Filters select conversations without filtering their detail pages. Manual merging is not provided. Thread membership is not proof of identity or delivery. Reply using a message resource ID, not the thread ID.", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Decimal integer without signs, whitespace or leading zeroes." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadDetail" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "subject": null, "last_activity_at": "2026-10-01T00:00:00.000Z", "message_count": 0, "received_count": 0, "accepted_count": 0, "rejected_count": 0, "unknown_count": 0, "messages": [], "next_cursor": null } } } }, "400": { "description": "`invalid_limit`: Use an integer from 1 to 100.\n\n`invalid_cursor`: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`content_unavailable`: Expected stored content is unavailable. Retry the read later.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "invalid_limit", "invalid_cursor", "content_unavailable", "internal_error" ] }, "patch": { "operationId": "updateThreadLabels", "tags": [ "threads" ], "summary": "Label a conversation", "description": "`PATCH /v1/threads/{thread_id}` adds or removes labels across all current received and sent members, not just one page. Use `Content-Type: application/json` with a body up to 20 KiB:\n\nThe [ordinary label validation rules](https://cherami.to/docs/api/labels/update-message-labels) apply. Changes publish together and preserve unrelated labels. Future replies do not inherit the changes. No sending or deletion permission is needed, and no sending allowance is consumed.\n\nReturns the update result.\n\n`id` is the canonical thread ID when members were selected. Counts describe updated copies, including those whose labels already matched, excluding any deleted before the update. `add_labels` and `remove_labels` contain the normalized changes, not each message's complete label set.\n\nInvalid changes return `400 invalid_labels`. Empty, missing or other-account threads return `404`.", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "200": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadLabelResult" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "message_count": 0, "received_count": 0, "sent_count": 0, "add_labels": [], "remove_labels": [] } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_labels`: Correct label names, changes, filter groups, or discovery prefix.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "not_found", "invalid_labels", "internal_error" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 20480 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelChange" }, "example": { "add_labels": [ "handled" ] } } } }, "x-request-body-limit": 20480, "x-example-body": { "add_labels": [ "handled" ] } }, "delete": { "operationId": "deleteThread", "tags": [ "threads" ], "summary": "Delete a conversation", "description": "`DELETE /v1/threads/{thread_id}` permanently deletes all messages currently in the conversation and their attachments. Confirm the exact conversation and full scope with the human. There is no trash or undo. Deletion requires the account's `can_delete` permission.\n\nReturns the deletion result.\n\n`id` is the canonical thread ID when members were selected; counts describe those selected messages. They are hidden from retrieval and search together. The inbox and saved drafts remain available. Sent-copy deletion does not cancel an already reserved send or refund its allowance.\n\nEmpty, missing or other-account threads return `404`; an account without deletion permission receives `403 operation_not_allowed`.", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owned Cherami resource ID returned by the API." } ], "responses": { "202": { "description": "Request accepted; inspect the response for its meaning.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedThread" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "inbox_id": "11111111-1111-4111-8111-111111111111", "message_count": 0, "received_count": 0, "sent_count": 0, "status": "deletion_pending", "message": "Example" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "not_found", "operation_not_allowed", "internal_error" ] } }, "/v1/feedback": { "post": { "operationId": "submitFeedback", "tags": [ "feedback" ], "summary": "Submit feedback", "description": "`POST /v1/feedback` requires bearer authentication and JSON. It does not require an inbox or available outbound quota.\n\nFor an inbox or sending allowance increase, describe the actual workflow and desired capacity. See [Free and custom allowances](https://cherami.to/pricing).\n\n`body` is required nonempty plain text. `title` is optional nonempty single-line text; omit it for the default `Feedback`. Unknown fields, attachments, caller-supplied sender identity, and malformed Unicode are rejected. The title rejects control characters; the body is preserved as supplied.\n\nThe entire UTF-8 JSON request, including field names and escaping, is capped at 20 KiB (20,480 bytes). There is no submission-rate limit and no outbound quota charge.\n\nFeedback uses the current verified human email as From and Reply-To and includes the account ID for review. **Replies go to the human, not the agent inbox.** Never include credentials or approval phrases.\n\nReturns `201`.\n\nThis confirms storage in our support inbox, not review or an approved allowance increase. Save the ID for correspondence. It grants no read/delete access to the support inbox. No feedback-status endpoint or automatic response is provided.\n\n`400`: invalid fields. `401`: missing/invalid credential. `413`: oversized JSON. `415`: non-JSON content type. An infrastructure `503` or lost response can have an unknown outcome. Do not blindly repeat POST; repeated submissions create duplicates.\n\nHumans and agents without credentials can email [hello@cherami.to](mailto:hello@cherami.to) directly. [Support guide](https://cherami.to/docs/guides/support)", "parameters": [], "responses": { "201": { "description": "Successful operation; inspect resource state and outcome fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResult" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "status": "received" } } } }, "400": { "description": "`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.\n\n`invalid_feedback`: Supply a nonempty plain-text body and, optionally, a nonempty single-line title; no other fields.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`body_too_large`: Reduce the JSON request to the endpoint's body limit.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: Send `Content-Type: application/json`.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`feedback_unavailable`: Feedback is unavailable or its submission outcome is unknown. Do not blindly repeat an uncertain submission.", "headers": { "X-Request-ID": { "description": "Support correlation ID, not an idempotency key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-codes": [ "unauthorized", "invalid_json", "body_too_large", "unsupported_media_type", "invalid_feedback", "feedback_unavailable" ], "requestBody": { "required": true, "description": "JSON object. Total UTF-8 request body limit: 20480 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackInput" }, "example": { "title": "Problem report", "body": "Describe the operation, expected result and request ID." } } } }, "x-request-body-limit": 20480, "x-example-body": { "title": "Problem report", "body": "Describe the operation, expected result and request ID." } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Cherami API key", "description": "Claim-issued ch_ credential. Shared account access. The HTTP API does not accept MCP OAuth tokens or browser session cookies." } }, "schemas": { "Mailbox": { "type": "object", "properties": { "address": { "type": "string", "description": "Bare ASCII address, at most 254 characters, local part at most 64. No display-name header syntax.", "maxLength": 254 }, "name": { "type": "string", "description": "Unicode name, trimmed; blank means unnamed. No control characters. At most 256 UTF-8 bytes after trimming.", "x-max-utf8-bytes": 256 } }, "required": [ "address" ], "additionalProperties": false }, "Label": { "type": "string", "description": "1–128 UTF-8 bytes after trimming. Well-formed Unicode without control characters; case-sensitive.", "x-max-utf8-bytes": 128 }, "AttachmentInput": { "type": "object", "properties": { "filename": { "type": "string", "description": "Nonempty, no control characters, slash or backslash. At most 255 UTF-8 bytes.", "minLength": 1, "x-max-utf8-bytes": 255 }, "type": { "type": "string", "description": "MIME type without parameters.", "maxLength": 127, "pattern": "^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$" }, "content": { "type": "string", "description": "Padded base64 original bytes, no whitespace; encoded length must be a multiple of four. Empty files are accepted.", "contentEncoding": "base64", "pattern": "^[A-Za-z0-9+/]*={0,2}$" } }, "required": [ "filename", "type", "content" ], "additionalProperties": false }, "StoredAttachment": { "type": "object", "properties": { "filename": { "type": "string", "description": "Nonempty, no control characters, slash or backslash. At most 255 UTF-8 bytes.", "minLength": 1, "x-max-utf8-bytes": 255 }, "type": { "type": "string", "description": "MIME type without parameters.", "maxLength": 127, "pattern": "^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$" }, "content": { "type": "string", "description": "Padded base64 original bytes, no whitespace; encoded length must be a multiple of four. Empty files are accepted.", "contentEncoding": "base64", "pattern": "^[A-Za-z0-9+/]*={0,2}$" }, "disposition": { "type": "string", "enum": [ "attachment", "inline" ] }, "contentId": { "type": "string", "description": "Present for source-derived inline files." } }, "required": [ "filename", "type", "content", "disposition" ] }, "Inbox": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "local_part": { "type": "string" }, "address": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sender_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "id", "local_part", "address", "name", "sender_name", "created_at" ] }, "CreatedInbox": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "local_part": { "type": "string" }, "address": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sender_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "replayed": { "type": "boolean" }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "id", "local_part", "address", "name", "sender_name", "created_at" ], "description": "Keyed creation adds both replay fields. Replay returns the inbox's current names, not the initial snapshot." }, "InboxAllowance": { "type": "object", "properties": { "allowance": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "unit": { "const": "inbox_slots" } }, "required": [ "allowance", "used", "remaining", "unit" ] }, "InboxList": { "type": "object", "properties": { "inboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } }, "inbox_limit": { "type": "integer", "minimum": 0, "description": "Authoritative current cap." }, "inbox_allowance": { "$ref": "#/components/schemas/InboxAllowance" } }, "required": [ "inboxes", "inbox_limit", "inbox_allowance" ] }, "CreateInbox": { "type": "object", "properties": { "local_part": { "type": "string", "description": "Trimmed and lowercased, then 1–64 ASCII letters, digits, hyphens or underscores with alphanumeric ends. Reserved, existing and retired addresses are unavailable." }, "name": { "anyOf": [ { "type": "string", "description": "Unicode name, trimmed; blank means unnamed. No control characters. At most 256 UTF-8 bytes after trimming.", "x-max-utf8-bytes": 256 }, { "type": "null" } ] }, "sender_name": { "anyOf": [ { "type": "string", "description": "Unicode name, trimmed; blank means unnamed. No control characters. At most 256 UTF-8 bytes after trimming.", "x-max-utf8-bytes": 256 }, { "type": "null" } ] }, "idempotency_key": { "type": "string", "description": "Retain a unique key, exact payload and first request time for this intended operation. Account-scoped protection lasts 24 hours without renewal.", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "required": [ "local_part" ], "additionalProperties": false }, "UpdateInbox": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "description": "Unicode name, trimmed; blank means unnamed. No control characters. At most 256 UTF-8 bytes after trimming.", "x-max-utf8-bytes": 256 }, { "type": "null" } ] }, "sender_name": { "anyOf": [ { "type": "string", "description": "Unicode name, trimmed; blank means unnamed. No control characters. At most 256 UTF-8 bytes after trimming.", "x-max-utf8-bytes": 256 }, { "type": "null" } ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "Policy": { "type": "object", "properties": { "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "enabled": { "type": "boolean" }, "addresses": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "domains": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "revision": { "type": "integer", "minimum": 0, "description": "Zero when unconfigured. Inspection does not reserve a policy for later mail." } }, "required": [ "inbox_id", "enabled", "addresses", "domains", "revision" ] }, "Preview": { "type": "object", "properties": { "text": { "type": "string", "description": "Beginning of selected text with normalized whitespace; empty is a valid extraction.", "maxLength": 300 }, "truncated": { "type": "boolean" }, "source": { "type": "string", "enum": [ "reply_text", "text", "html" ] } }, "required": [ "text", "truncated", "source" ] }, "ParsedAddress": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" } }, "required": [ "name", "address" ] }, { "type": "object", "properties": { "name": { "type": "string" }, "group": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" } }, "required": [ "name", "address" ] } } }, "required": [ "name", "group" ] } ], "description": "Sender-controlled MIME address or group, not verified identity." }, "ReceivedAttachment": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer", "minimum": 0 }, "mime_type": { "type": "string" }, "disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "related": { "type": "boolean" } }, "required": [ "id", "filename", "size", "mime_type", "disposition", "content_id", "related" ] }, "ReceivedContent": { "type": "object", "properties": { "from": { "anyOf": [ { "$ref": "#/components/schemas/ParsedAddress" }, { "type": "null" } ] }, "sender": { "anyOf": [ { "$ref": "#/components/schemas/ParsedAddress" }, { "type": "null" } ] }, "reply_to": { "type": "array", "items": { "$ref": "#/components/schemas/ParsedAddress" } }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/ParsedAddress" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/ParsedAddress" } }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/ParsedAddress" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "in_reply_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "references": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "date": { "anyOf": [ { "type": "string", "description": "Sender-controlled Date header: normalized when parseable, otherwise original header text. Not necessarily an ISO instant." }, { "type": "null" } ] }, "reply_text": { "anyOf": [ { "type": "string", "description": "Heuristic extraction; empty means no new text, null means unavailable. Original bodies remain authoritative." }, { "type": "null" } ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "html": { "anyOf": [ { "type": "string", "description": "Untrusted original prepared HTML." }, { "type": "null" } ] }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedAttachment" } } }, "required": [ "from", "sender", "reply_to", "to", "cc", "bcc", "subject", "message_id", "in_reply_to", "references", "date", "reply_text", "text", "html", "attachments" ] }, "ReceivedSummary": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "thread_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "envelope_from": { "type": "string" }, "envelope_to": { "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "processing_status": { "const": "ready" }, "labels": { "type": "array", "items": { "type": "string" } }, "preview": { "anyOf": [ { "$ref": "#/components/schemas/Preview" }, { "type": "null" } ] }, "from": { "anyOf": [ { "$ref": "#/components/schemas/ParsedAddress" }, { "type": "null" } ] } }, "required": [ "id", "inbox_id", "thread_id", "envelope_from", "envelope_to", "subject", "received_at", "processing_status", "labels", "preview", "from" ] }, { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "thread_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "envelope_from": { "type": "string" }, "envelope_to": { "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "processing_status": { "type": "string", "enum": [ "pending", "processing", "failed" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "preview": { "type": "null" } }, "required": [ "id", "inbox_id", "thread_id", "envelope_from", "envelope_to", "subject", "received_at", "processing_status", "labels", "preview" ] } ] }, "ReceivedDetail": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "thread_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "envelope_from": { "type": "string" }, "envelope_to": { "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "processing_status": { "const": "ready" }, "labels": { "type": "array", "items": { "type": "string" } }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "raw_size": { "type": "integer", "minimum": 0 }, "processed_at": { "anyOf": [ { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "content": { "$ref": "#/components/schemas/ReceivedContent" } }, "required": [ "id", "inbox_id", "thread_id", "envelope_from", "envelope_to", "subject", "received_at", "processing_status", "labels", "message_id", "raw_size", "processed_at", "content" ] }, { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "thread_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "envelope_from": { "type": "string" }, "envelope_to": { "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "processing_status": { "type": "string", "enum": [ "pending", "processing", "failed" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "raw_size": { "type": "integer", "minimum": 0 }, "processed_at": { "anyOf": [ { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] } }, "required": [ "id", "inbox_id", "thread_id", "envelope_from", "envelope_to", "subject", "received_at", "processing_status", "labels", "message_id", "raw_size", "processed_at" ] } ] }, "SentMetadata": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recipient_count": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "accepted", "rejected", "unknown" ] }, "provider_message_id": { "anyOf": [ { "type": "string", "description": "Provider's RFC Message-ID, not delivery confirmation." }, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string", "description": "Provider outcome code; not an HTTP application error." }, { "type": "null" } ] }, "thread_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "in_reply_to": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "inbox_id", "created_at", "recipient_count", "status", "provider_message_id", "error_code", "thread_id", "in_reply_to", "labels" ] }, "SentSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recipient_count": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "accepted", "rejected", "unknown" ] }, "provider_message_id": { "anyOf": [ { "type": "string", "description": "Provider's RFC Message-ID, not delivery confirmation." }, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string", "description": "Provider outcome code; not an HTTP application error." }, { "type": "null" } ] }, "thread_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "in_reply_to": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "preview": { "anyOf": [ { "$ref": "#/components/schemas/Preview" }, { "type": "null" } ] } }, "required": [ "id", "inbox_id", "created_at", "recipient_count", "status", "provider_message_id", "error_code", "thread_id", "in_reply_to", "labels", "preview" ] }, "Submission": { "type": "object", "properties": { "to": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Mailbox" }, { "type": "string", "description": "Historical bare-address value retained in full submissions." } ] } }, "cc": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Mailbox" }, { "type": "string", "description": "Historical bare-address value retained in full submissions." } ] } }, "bcc": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Mailbox" }, { "type": "string", "description": "Historical bare-address value retained in full submissions." } ] } }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/StoredAttachment" } }, "from": { "oneOf": [ { "$ref": "#/components/schemas/Mailbox" }, { "type": "string", "description": "Historical bare-address value retained in full submissions." } ] }, "headers": { "type": "object", "properties": { "In-Reply-To": { "type": "string" }, "References": { "type": "string" } }, "required": [ "In-Reply-To", "References" ] } }, "required": [ "from", "to", "cc", "bcc", "subject", "text", "attachments" ], "description": "Stored attributed submission, not final signed MIME. Historical recipient/address strings remain strings. Forwarded files may be inline." }, "SentDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recipient_count": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "accepted", "rejected", "unknown" ] }, "provider_message_id": { "anyOf": [ { "type": "string", "description": "Provider's RFC Message-ID, not delivery confirmation." }, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string", "description": "Provider outcome code; not an HTTP application error." }, { "type": "null" } ] }, "thread_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "in_reply_to": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "reply_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "submission": { "$ref": "#/components/schemas/Submission" } }, "required": [ "id", "inbox_id", "created_at", "recipient_count", "status", "provider_message_id", "error_code", "thread_id", "in_reply_to", "labels", "reply_text", "submission" ] }, "SendInput": { "type": "object", "properties": { "to": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50, "minItems": 1 }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "subject": { "type": "string", "description": "No control characters; at most 998 UTF-8 bytes. Must not be blank.", "x-max-utf8-bytes": 998 }, "text": { "type": "string", "description": "Required nonblank plain text." }, "html": { "type": "string", "description": "HTML alternative. Untrusted content, not sanitized markup." }, "attachments": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentInput" }, "maxItems": 32 }, { "type": "null" } ], "description": "Omitted or null means no attachments; an empty array also clears draft attachments." }, "in_reply_to": { "type": "string", "description": "Received or accepted sent resource ID in this inbox. The source must have usable reply headers.", "pattern": "^[a-f0-9-]{36}$" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." }, "idempotency_key": { "type": "string", "description": "Retain a unique key, exact payload and first request time for this intended operation. Account-scoped protection lasts 24 hours without renewal.", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "required": [ "to", "subject", "text" ], "additionalProperties": false, "description": "At most 50 combined To/Cc/Bcc entries. Local body/encoded-attachment sum is bounded to 5 MiB; generated MIME must also fit the provider's 5 MiB limit. No From override, arbitrary headers or inline attachment inputs." }, "ReplyInput": { "type": "object", "properties": { "message_id": { "type": "string", "description": "Received or accepted sent resource ID in this inbox. The source must have usable reply headers.", "pattern": "^[a-f0-9-]{36}$" }, "text": { "type": "string", "description": "Nonblank reply text; history is not automatically quoted." }, "html": { "type": "string", "description": "HTML alternative. Untrusted content, not sanitized markup." }, "attachments": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentInput" }, "maxItems": 32 }, { "type": "null" } ], "description": "Omitted or null means no attachments; an empty array also clears draft attachments." }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." }, "idempotency_key": { "type": "string", "description": "Retain a unique key, exact payload and first request time for this intended operation. Account-scoped protection lasts 24 hours without renewal.", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "required": [ "message_id", "text" ], "additionalProperties": false }, "ForwardInput": { "type": "object", "properties": { "message_id": { "type": "string", "description": "Received or accepted sent resource ID in this inbox. The source must have usable reply headers.", "pattern": "^[a-f0-9-]{36}$" }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50, "minItems": 1 }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "note": { "type": "string", "description": "Optional plain-text introduction." }, "include_attachments": { "type": "boolean", "default": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." }, "idempotency_key": { "type": "string", "description": "Retain a unique key, exact payload and first request time for this intended operation. Account-scoped protection lasts 24 hours without renewal.", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "required": [ "message_id", "to" ], "additionalProperties": false }, "SendReceipt": { "type": "object", "properties": { "limited": { "const": false }, "message": { "$ref": "#/components/schemas/SentMetadata" }, "outcome_persisted": { "type": "boolean" }, "replayed": { "type": "boolean" }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "limited", "message", "outcome_persisted" ], "description": "Inspect message.status even on HTTP 201. accepted is provider acceptance, not delivery. Preserve a known outcome when outcome_persisted is false; later reads may lag. Keyed receipts add replayed and expiry. Draft-association recovery adds replayed without requiring an expiry." }, "Quota": { "type": "object", "properties": { "allowance": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "next_capacity_at": { "anyOf": [ { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "next_capacity_amount": { "type": "integer", "minimum": 0 }, "window_hours": { "const": 24 }, "unit": { "const": "recipient_deliveries" }, "increase_request": { "type": "string" }, "policy_url": { "type": "string" } }, "required": [ "allowance", "used", "remaining", "next_capacity_at", "next_capacity_amount", "window_hours", "unit", "increase_request", "policy_url" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Programmatic error code. Handle unrecognized codes by status and operation-specific recovery." }, "message": { "type": "string", "description": "Human-readable context, not a stable string to match." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "InboxError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Programmatic error code. Handle unrecognized codes by status and operation-specific recovery." }, "message": { "type": "string", "description": "Human-readable context, not a stable string to match." }, "details": { "type": "object", "properties": { "allowance": { "$ref": "#/components/schemas/InboxAllowance" }, "increase_request": { "type": "string" }, "policy_url": { "type": "string" } }, "required": [ "allowance", "increase_request", "policy_url" ] } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "QuotaError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "const": "outbound_limit_reached" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "quota": { "$ref": "#/components/schemas/Quota" }, "requested_recipients": { "type": "integer", "minimum": 0 }, "reason": { "type": "string", "enum": [ "temporary_exhaustion", "message_exceeds_allowance" ] }, "sufficient_capacity_at": { "anyOf": [ { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "guidance": { "type": "string" } }, "required": [ "error", "quota", "requested_recipients", "reason", "sufficient_capacity_at", "guidance" ] }, "LabelChange": { "type": "object", "properties": { "add_labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." }, "remove_labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." } }, "required": [], "additionalProperties": false, "description": "At least one array must contain a label. A normalized label cannot occur in both arrays." }, "BulkLabelChange": { "type": "object", "properties": { "message_ids": { "type": "array", "items": { "type": "string", "description": "Lowercase hexadecimal UUID-shaped resource ID.", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$" }, "minItems": 1, "maxItems": 100 }, "add_labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." }, "remove_labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." } }, "required": [ "message_ids" ], "additionalProperties": false, "description": "At least one nonempty change array; additions and removals must not overlap. Duplicate IDs are updated once." }, "LabelResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "labels": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "labels" ] }, "LabelList": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "received_count": { "type": "integer", "minimum": 0 }, "sent_count": { "type": "integer", "minimum": 0 } }, "required": [ "name", "received_count", "sent_count" ] } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "labels", "next_cursor" ] }, "DraftMetadata": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "state": { "type": "string", "enum": [ "draft", "submitted" ] }, "subject": { "type": "string" }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "updated_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "sent_message_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] } }, "required": [ "id", "inbox_id", "state", "subject", "created_at", "updated_at", "sent_message_id" ] }, "CreatedDraft": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "state": { "type": "string", "enum": [ "draft", "submitted" ] }, "subject": { "type": "string" }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "updated_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "sent_message_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "replayed": { "type": "boolean" }, "idempotency_expires_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "id", "inbox_id", "state", "subject", "created_at", "updated_at", "sent_message_id" ] }, "DraftContent": { "type": "object", "properties": { "to": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "in_reply_to": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "labels": { "type": "array", "items": { "type": "string" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/StoredAttachment" } } }, "required": [ "to", "cc", "bcc", "subject", "text", "attachments" ] }, "DraftDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "state": { "type": "string", "enum": [ "draft", "submitted" ] }, "subject": { "type": "string" }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "updated_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "sent_message_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "from": { "$ref": "#/components/schemas/Mailbox" }, "content": { "$ref": "#/components/schemas/DraftContent" } }, "required": [ "id", "inbox_id", "state", "subject", "created_at", "updated_at", "sent_message_id", "from", "content" ] }, "CreateDraft": { "type": "object", "properties": { "to": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "subject": { "type": "string", "description": "No control characters; at most 998 UTF-8 bytes.", "x-max-utf8-bytes": 998 }, "text": { "type": "string", "description": "Plain-text body." }, "html": { "anyOf": [ { "type": "string", "description": "HTML alternative. Untrusted content, not sanitized markup." }, { "type": "null" } ] }, "attachments": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentInput" }, "maxItems": 32 }, { "type": "null" } ], "description": "Omitted or null means no attachments; an empty array also clears draft attachments." }, "in_reply_to": { "anyOf": [ { "type": "string", "description": "Received or accepted sent resource ID in this inbox. The source must have usable reply headers.", "pattern": "^[a-f0-9-]{36}$" }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." }, "idempotency_key": { "type": "string", "description": "Retain a unique key, exact payload and first request time for this intended operation. Account-scoped protection lasts 24 hours without renewal.", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "source": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "reply", "reply-all" ] }, "message_id": { "type": "string", "description": "Received or accepted sent resource ID in this inbox. The source must have usable reply headers.", "pattern": "^[a-f0-9-]{36}$" } }, "required": [ "action", "message_id" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "forward" }, "message_id": { "type": "string", "description": "Received or accepted sent resource ID in this inbox. The source must have usable reply headers.", "pattern": "^[a-f0-9-]{36}$" }, "include_attachments": { "type": "boolean", "default": true } }, "required": [ "action", "message_id" ], "additionalProperties": false } ] } }, "required": [], "additionalProperties": false, "description": "Incomplete content is allowed, including missing/empty recipients, subject and text. At most 50 combined recipients and 32 attachments; same local content bound as sending. With a forward source, attachments cannot also be supplied; text is the introductory note on creation only." }, "UpdateDraft": { "type": "object", "properties": { "to": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "maxItems": 50 }, "subject": { "type": "string", "description": "No control characters; at most 998 UTF-8 bytes.", "x-max-utf8-bytes": 998 }, "text": { "type": "string", "description": "Plain-text body." }, "html": { "anyOf": [ { "type": "string", "description": "HTML alternative. Untrusted content, not sanitized markup." }, { "type": "null" } ] }, "attachments": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentInput" }, "maxItems": 32 }, { "type": "null" } ], "description": "Omitted or null means no attachments; an empty array also clears draft attachments." }, "in_reply_to": { "anyOf": [ { "type": "string", "description": "Received or accepted sent resource ID in this inbox. The source must have usable reply headers.", "pattern": "^[a-f0-9-]{36}$" }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "maxItems": 32, "description": "Trimmed, deduplicated and case-sensitive. Order is not significant." } }, "required": [], "additionalProperties": false, "minProperties": 1, "description": "Only supplied fields change; arrays replace their entire lists. No source, version, review lock or idempotency key. Submitted drafts cannot be edited." }, "SendDraft": { "type": "object", "properties": { "idempotency_key": { "type": "string", "description": "Retain a unique key, exact payload and first request time for this intended operation. Account-scoped protection lasts 24 hours without renewal.", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "required": [], "additionalProperties": false }, "ThreadMetadata": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_activity_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "message_count": { "type": "integer", "minimum": 0 }, "received_count": { "type": "integer", "minimum": 0 }, "accepted_count": { "type": "integer", "minimum": 0 }, "rejected_count": { "type": "integer", "minimum": 0 }, "unknown_count": { "type": "integer", "minimum": 0 } }, "required": [ "id", "inbox_id", "subject", "last_activity_at", "message_count", "received_count", "accepted_count", "rejected_count", "unknown_count" ] }, "ThreadSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_activity_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "message_count": { "type": "integer", "minimum": 0 }, "received_count": { "type": "integer", "minimum": 0 }, "accepted_count": { "type": "integer", "minimum": 0 }, "rejected_count": { "type": "integer", "minimum": 0 }, "unknown_count": { "type": "integer", "minimum": 0 }, "matching_message_ids": { "type": "array", "items": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "maxItems": 100 }, "matching_message_count": { "type": "integer", "minimum": 0 } }, "required": [ "id", "inbox_id", "subject", "last_activity_at", "message_count", "received_count", "accepted_count", "rejected_count", "unknown_count" ] }, "ThreadSentDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "created_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recipient_count": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "accepted", "rejected", "unknown" ] }, "provider_message_id": { "anyOf": [ { "type": "string", "description": "Provider's RFC Message-ID, not delivery confirmation." }, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string", "description": "Provider outcome code; not an HTTP application error." }, { "type": "null" } ] }, "thread_id": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "in_reply_to": { "anyOf": [ { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "direction": { "const": "sent" }, "timestamp": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "reply_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "submission": { "type": "object", "properties": { "to": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Mailbox" }, { "type": "string", "description": "Historical bare-address value retained in full submissions." } ] } }, "cc": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Mailbox" }, { "type": "string", "description": "Historical bare-address value retained in full submissions." } ] } }, "bcc": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Mailbox" }, { "type": "string", "description": "Historical bare-address value retained in full submissions." } ] } }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } }, "required": [ "id", "filename", "mime_type", "size" ] } }, "from": { "oneOf": [ { "$ref": "#/components/schemas/Mailbox" }, { "type": "string", "description": "Historical bare-address value retained in full submissions." } ] }, "headers": { "type": "object", "properties": { "In-Reply-To": { "type": "string" }, "References": { "type": "string" } }, "required": [ "In-Reply-To", "References" ] } }, "required": [ "from", "to", "cc", "bcc", "subject", "text", "attachments" ] } }, "required": [ "id", "inbox_id", "created_at", "recipient_count", "status", "provider_message_id", "error_code", "thread_id", "in_reply_to", "labels", "direction", "timestamp", "reply_text", "submission" ] }, "ThreadReceivedDetail": { "allOf": [ { "$ref": "#/components/schemas/ReceivedDetail" }, { "type": "object", "properties": { "direction": { "const": "received" }, "timestamp": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "direction", "timestamp" ] } ] }, "ThreadDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_activity_at": { "type": "string", "description": "UTC service instant with milliseconds and Z suffix.", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "message_count": { "type": "integer", "minimum": 0 }, "received_count": { "type": "integer", "minimum": 0 }, "accepted_count": { "type": "integer", "minimum": 0 }, "rejected_count": { "type": "integer", "minimum": 0 }, "unknown_count": { "type": "integer", "minimum": 0 }, "messages": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ThreadReceivedDetail" }, { "$ref": "#/components/schemas/ThreadSentDetail" } ] } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "inbox_id", "subject", "last_activity_at", "message_count", "received_count", "accepted_count", "rejected_count", "unknown_count", "messages", "next_cursor" ] }, "ThreadLabelResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "message_count": { "type": "integer", "minimum": 0 }, "received_count": { "type": "integer", "minimum": 0 }, "sent_count": { "type": "integer", "minimum": 0 }, "add_labels": { "type": "array", "items": { "type": "string" } }, "remove_labels": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "inbox_id", "message_count", "received_count", "sent_count", "add_labels", "remove_labels" ] }, "Deleted": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "status": { "const": "deletion_pending" }, "message": { "type": "string" } }, "required": [ "id", "status", "message" ] }, "DeletedDraft": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "status": { "const": "deletion_pending" }, "message": { "type": "string" } }, "required": [ "id", "status", "message" ] }, "DeletedThread": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "inbox_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "message_count": { "type": "integer", "minimum": 0 }, "received_count": { "type": "integer", "minimum": 0 }, "sent_count": { "type": "integer", "minimum": 0 }, "status": { "const": "deletion_pending" }, "message": { "type": "string" } }, "required": [ "id", "inbox_id", "message_count", "received_count", "sent_count", "status", "message" ] }, "SignupInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "SignupResult": { "type": "object", "properties": { "status": { "const": "awaiting_human" }, "approval_url": { "const": "https://cherami.to/claim" }, "message": { "type": "string" } }, "required": [ "status", "approval_url", "message" ] }, "ClaimInput": { "type": "object", "properties": { "phrase": { "type": "string", "description": "Human-approved, one-use six-word phrase. Case and whitespace are normalized." }, "discovery_source": { "description": "Optional initial signup research. Intended as trimmed text up to 500 UTF-16 code units; blank, malformed or overlong values are ignored, not rejected." }, "intended_use": { "description": "Optional initial signup research with the same best-effort handling as discovery_source. Never include secrets or private conversation excerpts." } }, "required": [ "phrase" ], "additionalProperties": false }, "ClaimResult": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "credential": { "type": "string", "description": "Returned once. Store privately; never print in chat or logs." }, "token_type": { "const": "Bearer" }, "message": { "type": "string" } }, "required": [ "account_id", "credential", "token_type", "message" ] }, "FeedbackInput": { "type": "object", "properties": { "title": { "type": "string", "description": "Optional nonempty single-line text; defaults to Feedback. No control characters or malformed Unicode." }, "body": { "type": "string", "description": "Nonempty well-formed Unicode plain text, preserved as supplied." } }, "required": [ "body" ], "additionalProperties": false }, "FeedbackResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Cherami resource ID, distinct from the RFC Message-ID. Use the returned value." }, "status": { "const": "received" } }, "required": [ "id", "status" ] } } } }