{"openapi":"3.1.0","info":{"title":"Postyard API","description":"Email host for developers and AI agents: domains, mailboxes, conversations, drafts, sending and webhooks. Authenticate with `Authorization: Bearer py_live_...`. Agents: read /llms.txt for the guide (scopes, errors, idempotency, webhooks, limits) and /agent-setup.md for a first-session prompt. The MCP connector lives at /mcp.","license":{"name":""},"version":"1"},"paths":{"/v1/api-keys":{"get":{"tags":["routes::api_keys"],"summary":"List API keys, including revoked ones. Secrets are never returned.","operationId":"list_api_keys","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialList"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"post":{"tags":["routes::api_keys"],"summary":"Create an API key. The secret is returned only here.","operationId":"create_api_key","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedApiKey"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/api-keys/{id}":{"delete":{"tags":["routes::api_keys"],"summary":"Revoke an API key. It stops working immediately.","operationId":"revoke_api_key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/connections":{"get":{"tags":["routes::connections"],"summary":"List OAuth connections, newest first: all of them with `credentials.manage`, otherwise only\nyour own.","operationId":"list_connections","parameters":[{"name":"cursor","in":"query","description":"Opaque cursor from a previous page's `next_cursor`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"1 to 100, default 50.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionList"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/connections/{id}":{"patch":{"tags":["routes::connections"],"summary":"Change a connection's scopes or restriction, never beyond your own.","operationId":"update_connection","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConnectionRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/connections/{id}/restore":{"post":{"tags":["routes::connections"],"summary":"Restore a revoked connection. Requires `credentials.manage`.","operationId":"restore_connection","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/connections/{id}/revoke":{"post":{"tags":["routes::connections"],"summary":"Revoke a connection. Its next call is refused; an admin can restore it.","operationId":"revoke_connection","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/conversations":{"get":{"tags":["routes::messages"],"summary":"List conversations, newest first, with keyset paging.","operationId":"list_conversations","parameters":[{"name":"mailbox_id","in":"query","description":"Restrict to one mailbox. Without it, every mailbox the caller may read.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"folder","in":"query","description":"A conversation is listed under a folder when any of its messages is in it. Default `inbox`.","required":false,"schema":{"$ref":"#/components/schemas/Folder"}},{"name":"unread_only","in":"query","description":"Only conversations with an unread inbound message.","required":false,"schema":{"type":"boolean"}},{"name":"include_handled","in":"query","description":"`false` hides conversations whose inbound messages are all handled. Default `true`.","required":false,"schema":{"type":"boolean"}},{"name":"since","in":"query","description":"Only conversations whose last message is at or after this time.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","description":"Opaque cursor from a previous page's `next_cursor`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"1 to 100, default 25.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationPage"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/conversations/{id}":{"get":{"tags":["routes::messages"],"summary":"Get a conversation with its messages, oldest first.","operationId":"get_conversation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDetail"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/domains":{"get":{"tags":["routes::domains"],"summary":"List domains the caller can manage.","operationId":"list_domains","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainList"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"post":{"tags":["routes::domains"],"summary":"Add a domain and get the DNS records to publish.","operationId":"create_domain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddDomainRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDetail"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/domains/{id}":{"get":{"tags":["routes::domains"],"summary":"Get a domain with the status of each DNS record.","operationId":"get_domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDetail"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"delete":{"tags":["routes::domains"],"summary":"Delete a domain.","operationId":"delete_domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/domains/{id}/check":{"post":{"tags":["routes::domains"],"summary":"Re-check the domain's DNS now.","operationId":"check_domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDetail"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/drafts/{id}":{"delete":{"tags":["routes::sending"],"summary":"Delete a draft.","operationId":"delete_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"patch":{"tags":["routes::sending"],"summary":"Replace a draft's content. The message id stays the same.","operationId":"update_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/drafts/{id}/send":{"post":{"tags":["routes::sending"],"summary":"Send a draft. Needs the send scope. With an `Idempotency-Key`, a retry returns the same send.","operationId":"send_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"1 to 255 printable ASCII characters; makes the call safely retryable. Applies to the send routes only (drafts/{id}/send, mailboxes/{id}/messages, messages/{id}/reply); ignored elsewhere.","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/early-access":{"post":{"tags":["routes::early_access"],"summary":"Request a private-beta invitation. A new request, a duplicate within 24 hours and a filled\nspam trap (`company_website`) all receive the same 202; this endpoint never sends an email to\nthe supplied address. At most 5 requests per client address and 200 in all per hour.","operationId":"request_early_access","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EarlyAccessRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid email address, a field too long, or a malformed body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"A browser origin other than the public site","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/exports/{id}":{"get":{"tags":["routes::exports"],"summary":"One export's status.","operationId":"get_export","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/exports/{id}/download":{"get":{"tags":["routes::exports"],"summary":"Download a ready export (`application/gzip`, streamed). 409 `export_not_ready` while pending,\n410 `export_expired` after the 24 hours.","operationId":"download_export","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/gzip":{"schema":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"`export_not_ready` or `export_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"410":{"description":"`export_expired`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes":{"get":{"tags":["routes::mailboxes"],"summary":"List the mailboxes the caller can see.","operationId":"list_mailboxes","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxList"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"post":{"tags":["routes::mailboxes"],"summary":"Create a mailbox on a verified domain.","operationId":"create_mailbox","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMailboxRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}":{"get":{"tags":["routes::mailboxes"],"summary":"Get a mailbox.","operationId":"get_mailbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxView"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"delete":{"tags":["routes::mailboxes"],"summary":"Delete a mailbox and all its mail.","operationId":"delete_mailbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"patch":{"tags":["routes::mailboxes"],"summary":"Change a mailbox's display name or suspend or resume it.","operationId":"update_mailbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMailboxRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxView"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/aliases":{"post":{"tags":["routes::mailboxes"],"summary":"Add an alias address to a mailbox.","operationId":"add_mailbox_alias","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAliasRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxView"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/aliases/{address}":{"delete":{"tags":["routes::mailboxes"],"summary":"Remove an alias address from a mailbox.","operationId":"remove_mailbox_alias","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxView"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/app-passwords":{"get":{"tags":["routes::mailboxes"],"summary":"List a mailbox's active app passwords. Secrets are never returned.","operationId":"list_app_passwords","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppPasswordList"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"post":{"tags":["routes::mailboxes"],"summary":"Create an app password for IMAP and SMTP. The secret is returned only here.","operationId":"create_app_password","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAppPasswordRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedAppPassword"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/app-passwords/{app_password_id}":{"delete":{"tags":["routes::mailboxes"],"summary":"Revoke an app password. It stops working immediately.","operationId":"revoke_app_password","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"app_password_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/attachments":{"post":{"tags":["routes::sending"],"summary":"Upload a file to attach to a draft. Needs the draft scope.","operationId":"upload_attachment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadForm"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadedAttachment"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/connection-settings":{"get":{"tags":["routes::mailboxes"],"summary":"IMAP and SMTP settings for connecting a mail client to the mailbox.","operationId":"get_connection_settings","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionSettings"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/drafts":{"post":{"tags":["routes::sending"],"summary":"Create a draft in the mailbox's Drafts folder.","operationId":"create_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/exports":{"get":{"tags":["routes::exports"],"summary":"A mailbox's recent exports, newest first.","operationId":"list_mailbox_exports","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportList"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"post":{"tags":["routes::exports"],"summary":"Start exporting a mailbox as a gzipped mbox file. One export runs at a time per mailbox; poll\n`GET /v1/exports/{id}` until `ready`, then download it within 24 hours.","operationId":"create_mailbox_export","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"`export_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many live exports for the mailbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the server is low on storage space. Retry later.","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/grants":{"get":{"tags":["routes::mailboxes"],"summary":"List the organization members granted access to a mailbox.","operationId":"list_mailbox_grants","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantList"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"post":{"tags":["routes::mailboxes"],"summary":"Grant an organization member access to a mailbox.","operationId":"grant_mailbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantRequest"}}},"required":true},"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/grants/{clerk_user_id}":{"delete":{"tags":["routes::mailboxes"],"summary":"Remove a member's access to a mailbox.","operationId":"revoke_mailbox_grant","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"clerk_user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/mailboxes/{id}/messages":{"post":{"tags":["routes::sending"],"summary":"Send a new message from the mailbox. Needs the send scope.","operationId":"send_message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"1 to 255 printable ASCII characters; makes the call safely retryable. Applies to the send routes only (drafts/{id}/send, mailboxes/{id}/messages, messages/{id}/reply); ignored elsewhere.","required":false,"schema":{"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/me":{"get":{"tags":["routes::me"],"summary":"The authenticated actor, its organization, scopes and restriction.","operationId":"get_me","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/messages/{id}":{"get":{"tags":["routes::messages"],"summary":"Get a message with its body. Reading does not mark it read.","description":"`html` is the sender's raw HTML: never render it. With `display=1`, `html` is instead the\ndocument prepared for display (see `display-html`; `remote=1` allows remote images), or `null`\nwith `html_too_large` when it exceeds 4 MiB.","operationId":"get_message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"display","in":"query","description":"`1`: return `html` prepared for display instead of the raw HTML. Default `0`.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"remote","in":"query","description":"With `display=1`: `1` allows remote images (`https:`). Default `0`.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/messages/{id}/attachments/{attachment_id}":{"get":{"tags":["routes::messages"],"summary":"Download an attachment as `application/octet-stream`-safe bytes.","operationId":"get_attachment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"attachment_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/messages/{id}/display-html":{"get":{"tags":["routes::messages"],"summary":"The message's HTML prepared for display: a CSP that blocks all network fetches (remote\nimages only with `remote=1`) and `<base target=\"_blank\">` open the `<head>`, and meta\nrefresh is removed. Authorized exactly like `get_message`. Render it only in a sandboxed\niframe without `allow-scripts` or `allow-same-origin`.","operationId":"get_message_display_html","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"remote","in":"query","description":"`1` allows remote images (`https:`); `0` (default) blocks every network fetch.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisplayHtml"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/messages/{id}/handled":{"post":{"tags":["routes::messages"],"summary":"Mark a message handled or not. Does not change read state.","operationId":"set_message_handled","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandledRequest"}}},"required":true},"responses":{"204":{},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/messages/{id}/read":{"post":{"tags":["routes::messages"],"summary":"Mark a message read or unread.","operationId":"set_message_read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadRequest"}}},"required":true},"responses":{"204":{},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/messages/{id}/reply":{"post":{"tags":["routes::sending"],"summary":"Reply to a message and send the reply. Needs the send scope.","operationId":"reply_to_message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"1 to 255 printable ASCII characters; makes the call safely retryable. Applies to the send routes only (drafts/{id}/send, mailboxes/{id}/messages, messages/{id}/reply); ignored elsewhere.","required":false,"schema":{"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/messages/{id}/reply-drafts":{"post":{"tags":["routes::sending"],"summary":"Create a reply draft. Recipients are derived from the original message.","operationId":"create_reply_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageView"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Unavailable: the request may or may not have taken effect, or a resource is busy. Retry later (same Idempotency-Key for sends).","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/request-logs":{"get":{"tags":["routes::request_logs"],"summary":"List recent API and MCP requests for the organization, newest first. Kept 30 days. Rows\nhold the route template, never paths with IDs, query strings, bodies or headers.","operationId":"list_request_logs","parameters":[{"name":"status_class","in":"query","description":"First digit of the status: 2, 4 or 5.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"credential_id","in":"query","description":"Restrict to one API key or connection.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"error_code","in":"query","description":"Restrict to one error code, such as `missing_scope`.","required":false,"schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Opaque cursor from a previous page's `next_cursor`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"1 to 100, default 25.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogPage"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/sends":{"get":{"tags":["routes::sends"],"summary":"List sent messages with their recipients' latest status, newest first. Sends are kept 180 days.","operationId":"list_sends","parameters":[{"name":"mailbox_id","in":"query","description":"Restrict to one mailbox. Without it, every mailbox the caller may read.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","description":"Opaque cursor from a previous page's `next_cursor`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"1 to 100, default 25.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPage"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/sends/{id}":{"get":{"tags":["routes::sends"],"summary":"One send with its per-recipient delivery history.","operationId":"get_send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDetail"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/setup-status":{"get":{"tags":["routes::setup"],"summary":"Setup progress of the organization: domain, mailbox, first send, first receive, agent.","operationId":"get_setup_status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetupStatus"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/support":{"post":{"tags":["routes::support"],"summary":"Contact Postyard support from the web app. People signed in to the app only (API keys and\nagent connections get 403); 10 requests per organization in any 24 hours (429). The request\nis emailed to support with the requester's email address as Reply-To.","operationId":"create_support_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportReceipt"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/suppressions":{"get":{"tags":["routes::sends"],"summary":"Addresses Postyard refuses to send to for this organization (hard bounces, complaints).","operationId":"list_suppressions","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionList"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/suppressions/{address}":{"delete":{"tags":["routes::sends"],"summary":"Remove an address from the suppression list.","operationId":"remove_suppression","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/usage":{"get":{"tags":["routes::usage"],"summary":"Usage and limits for the current usage period.","operationId":"get_usage","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReport"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/webhook-deliveries/{id}/replay":{"post":{"tags":["routes::webhooks"],"summary":"Deliver the same event again as a new delivery.","operationId":"replay_webhook_delivery","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryView"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/webhooks":{"get":{"tags":["routes::webhooks"],"summary":"List webhook endpoints.","operationId":"list_webhooks","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointList"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]},"post":{"tags":["routes::webhooks"],"summary":"Create a webhook endpoint. The signing secret is returned only here.","operationId":"create_webhook","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEndpointRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedEndpoint"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/webhooks/{id}":{"delete":{"tags":["routes::webhooks"],"summary":"Delete a webhook endpoint and its delivery history.","operationId":"delete_webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/webhooks/{id}/deliveries":{"get":{"tags":["routes::webhooks"],"summary":"Recent deliveries for an endpoint, including attempts.","operationId":"list_webhook_deliveries","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"path","description":"1 to 200, default 50.","required":true,"schema":{"type":["integer","null"],"format":"int64"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryList"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/webhooks/{id}/rotate-secret":{"post":{"tags":["routes::webhooks"],"summary":"Issue a new signing secret. The old one stays valid for 24 hours.","operationId":"rotate_webhook_secret","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotatedSecret"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}},"/v1/webhooks/{id}/test":{"post":{"tags":["routes::webhooks"],"summary":"Send a `webhook.test` event to this endpoint only.","operationId":"send_test_webhook_event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryView"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearer":[]}]}}},"components":{"schemas":{"ActorView":{"oneOf":[{"type":"object","required":["clerk_user_id","role","type"],"properties":{"clerk_user_id":{"type":"string"},"role":{"type":"string","description":"`admin` or `member`"},"type":{"type":"string","enum":["member"]}}},{"type":"object","required":["credential_id","type"],"properties":{"credential_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["api_key"]}}},{"type":"object","required":["credential_id","clerk_user_id","type"],"properties":{"clerk_user_id":{"type":"string"},"credential_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["oauth"]}}}]},"AddAliasRequest":{"type":"object","required":["address"],"properties":{"address":{"type":"string"}}},"AddDomainRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A domain name or URL, such as `example.com`. Normalized before use."}}},"AppPasswordList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AppPasswordView"}}}},"AppPasswordView":{"type":"object","required":["id","name","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"AttachmentView":{"type":"object","required":["id","content_type","size"],"properties":{"content_type":{"type":"string"},"id":{"type":"string","description":"The blob id; pass it to the attachment download route."},"name":{"type":["string","null"]},"size":{"type":"integer","format":"int64"}}},"AttemptView":{"type":"object","required":["attempted_at","duration_ms"],"properties":{"attempted_at":{"type":"string","format":"date-time"},"duration_ms":{"type":"integer","format":"int32"},"error":{"type":["string","null"]},"status_code":{"type":["integer","null"],"format":"int32"}}},"ConnectionList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionView"}},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}},"ConnectionSettings":{"type":"object","required":["imap_host","imap_port","smtp_host","smtp_ports","username"],"properties":{"imap_host":{"type":"string"},"imap_port":{"type":"integer","format":"int32","description":"Implicit TLS.","minimum":0},"smtp_host":{"type":"string"},"smtp_ports":{"type":"array","items":{"type":"integer","format":"int32","minimum":0},"description":"Implicit TLS (465) and STARTTLS (587)."},"username":{"type":"string","description":"The mailbox's primary address."}}},"ConnectionView":{"type":"object","required":["id","client_id","clerk_user_id","scopes","restriction","created_at"],"properties":{"clerk_user_id":{"type":"string"},"client_id":{"type":"string","description":"The OAuth client ID, shown as is (for a client ID metadata document it is a URL)."},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"last_used_at":{"type":["string","null"],"format":"date-time"},"restriction":{"type":"object","description":"`{\"type\":\"all\"}`, `{\"type\":\"domains\",\"ids\":[..]}` or `{\"type\":\"mailboxes\",\"ids\":[..]}`."},"revoked_at":{"type":["string","null"],"format":"date-time"},"scopes":{"type":"array","items":{"type":"string"},"description":"Scope names such as `mail.read`."}}},"ConversationDetail":{"type":"object","required":["conversation","messages"],"properties":{"conversation":{"$ref":"#/components/schemas/ConversationSummary"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/MessageView"}}}},"ConversationPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ConversationSummary"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` on the last page."}}},"ConversationSummary":{"type":"object","required":["id","mailbox_id","mailbox_address","subject","participants","preview","last_message_at","message_count","unread","has_attachments"],"properties":{"has_attachments":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"last_message_at":{"type":"string","format":"date-time"},"latest_from":{"type":["string","null"],"description":"The sender of the newest message that is not a draft. Lets a list name a conversation\nwhose `participants` is empty because only the mailbox's own addresses took part (mail\nfrom one of its aliases, or to itself)."},"mailbox_address":{"type":"string"},"mailbox_id":{"type":"string","format":"uuid"},"message_count":{"type":"integer","format":"int32"},"participants":{"type":"array","items":{"type":"string"},"description":"Distinct senders and recipients, the mailbox's own address excluded, at most 10."},"preview":{"type":"string"},"subject":{"type":"string"},"unread":{"type":"boolean","description":"Any inbound message is unread."}}},"CreateApiKeyRequest":{"type":"object","required":["name","preset"],"properties":{"name":{"type":"string"},"preset":{"$ref":"#/components/schemas/PresetName","description":"`read_draft`, `read_draft_send` or `admin`."},"restriction":{"type":["object","null"],"description":"Defaults to the caller's own restriction."}}},"CreateAppPasswordRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}},"CreateEndpointRequest":{"type":"object","required":["url"],"properties":{"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"},"description":"Event type names such as `message.received`, or `*` for all. Defaults to `[\"*\"]`."},"restriction":{"type":["object","null"],"description":"Defaults to the caller's own restriction."},"url":{"type":"string"}}},"CreateMailboxRequest":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"The full address, such as `alice@example.com`; the domain must be verified."},"display_name":{"type":["string","null"]}}},"CreatedApiKey":{"type":"object","required":["credential","secret"],"properties":{"credential":{"$ref":"#/components/schemas/CredentialView"},"secret":{"type":"string","description":"Shown only here. Store it now; it cannot be retrieved later."}}},"CreatedAppPassword":{"type":"object","required":["view","secret"],"properties":{"secret":{"type":"string","description":"Shown only here. Postyard does not store it; Stalwart does."},"view":{"$ref":"#/components/schemas/AppPasswordView"}}},"CreatedEndpoint":{"type":"object","required":["endpoint","secret"],"properties":{"endpoint":{"$ref":"#/components/schemas/EndpointView"},"secret":{"type":"string","description":"Shown only here and on rotation."}}},"CredentialList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CredentialView"}}}},"CredentialView":{"type":"object","required":["id","kind","name","scopes","restriction","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"key_prefix":{"type":["string","null"],"description":"The first characters of the key, to recognise it by."},"kind":{"type":"string","description":"`api_key` or `oauth`."},"last_used_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"restriction":{"type":"object","description":"`{\"type\":\"all\"}`, `{\"type\":\"domains\",\"ids\":[..]}` or `{\"type\":\"mailboxes\",\"ids\":[..]}`."},"revoked_at":{"type":["string","null"],"format":"date-time"},"scopes":{"type":"array","items":{"type":"string"},"description":"Scope names such as `mail.read`."}}},"DeliveryEventView":{"type":"object","required":["recipient","status","occurred_at","source"],"properties":{"detail":{"type":["string","null"]},"occurred_at":{"type":"string","format":"date-time"},"recipient":{"type":"string"},"source":{"type":"string","description":"`hook`, `stalwart` or `ses`."},"status":{"type":"string"}}},"DeliveryList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryView"}}}},"DeliveryView":{"type":"object","required":["id","endpoint_id","event_id","event_type","status","attempts","created_at","updated_at","attempt_log"],"properties":{"attempt_log":{"type":"array","items":{"$ref":"#/components/schemas/AttemptView"}},"attempts":{"type":"integer","format":"int32"},"created_at":{"type":"string","format":"date-time"},"endpoint_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_error":{"type":["string","null"]},"last_status_code":{"type":["integer","null"],"format":"int32"},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"replay_of":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","description":"`pending`, `succeeded` or `failed`."},"updated_at":{"type":"string","format":"date-time"}}},"DisplayHtml":{"type":"object","required":["too_large"],"properties":{"html":{"type":["string","null"],"description":"A complete document for `<iframe sandbox=\"allow-popups allow-popups-to-escape-sandbox\" srcdoc>`. `null` when the message has no HTML part or it is too large."},"too_large":{"type":"boolean","description":"The HTML part exceeds 4 MiB and is not prepared; show the text part instead."}}},"DomainDetail":{"type":"object","required":["domain","records","dkim_pending"],"properties":{"dkim_pending":{"type":"boolean","description":"True until ownership is verified and the DKIM records exist."},"domain":{"$ref":"#/components/schemas/DomainView"},"records":{"type":"array","items":{"$ref":"#/components/schemas/RecordRow"}}}},"DomainList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DomainView"}}}},"DomainView":{"type":"object","required":["id","name","status","ownership_verified","can_receive","can_send","ownership_record_missing","sending_keys_pending","created_at"],"properties":{"can_receive":{"type":"boolean"},"can_send":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"last_checked_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"ownership_record_missing":{"type":"boolean","description":"Verified, but the ownership TXT record is not currently passing. Ownership stays\nverified, yet the record should stay published."},"ownership_verified":{"type":"boolean"},"sending_keys_pending":{"type":"boolean","description":"Ownership is verified and Postyard is still creating the domain's sending (DKIM) keys, so\nits DKIM records are not known yet. Usually brief; nothing to publish meanwhile."},"status":{"type":"string","description":"`pending` (ownership not proven), `partial` or `ready` (can receive and send)."}}},"DraftInput":{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/UploadedAttachment"}},"bcc":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"from":{"type":["string","null"],"description":"One of the mailbox's own addresses. Default: its primary address."},"subject":{"type":"string"},"text":{"type":"string"},"to":{"type":"array","items":{"type":"string"}}}},"EarlyAccessRequest":{"type":"object","required":["email"],"properties":{"analytics_device_id":{"type":["string","null"],"description":"Optional Amplitude device id from an already consented browser, for the acquisition\nfunnel: 5 to 128 letters, digits, `.`, `_` or `-`. Anything else is ignored, never an error.","maxLength":128},"company_website":{"type":["string","null"],"description":"The form's hidden spam trap: people leave it empty. Filled, the request answers 202 and\nnothing is stored. (`honeypot` is accepted as an older name.)"},"email":{"type":"string","description":"Work email address. Requests are stored and emailed to Postyard support only.","maxLength":254},"referrer":{"type":["string","null"],"description":"The referring page's origin only, such as `https://news.ycombinator.com`.","maxLength":300},"use_case":{"type":["string","null"],"description":"What the requester will use Postyard for.","maxLength":500},"utm_campaign":{"type":["string","null"],"maxLength":100},"utm_content":{"type":["string","null"],"maxLength":100},"utm_medium":{"type":["string","null"],"maxLength":100},"utm_source":{"type":["string","null"],"maxLength":100},"utm_term":{"type":["string","null"],"maxLength":100}}},"EndpointList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EndpointView"}}}},"EndpointView":{"type":"object","required":["id","url","description","event_types","restriction","consecutive_failures","created_at"],"properties":{"consecutive_failures":{"type":"integer","format":"int32"},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"disabled_at":{"type":["string","null"],"format":"date-time"},"event_types":{"type":"array","items":{"type":"string"}},"id":{"type":"string","format":"uuid"},"restriction":{"type":"object","description":"`{\"type\":\"all\"}`, `{\"type\":\"domains\",\"ids\":[..]}` or `{\"type\":\"mailboxes\",\"ids\":[..]}`."},"url":{"type":"string"}}},"ErrorBody":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","description":"Stable snake_case code, e.g. `not_found`."},"message":{"type":"string"},"request_id":{"type":"string"}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}},"ExportList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExportView"}}}},"ExportView":{"type":"object","required":["id","mailbox_id","status","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"error":{"type":["string","null"],"description":"Why a `failed` export failed, or a note on a `ready` one (skipped messages)."},"expires_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"mailbox_id":{"type":"string","format":"uuid"},"message_count":{"type":["integer","null"],"format":"int32"},"size_bytes":{"type":["integer","null"],"format":"int64"},"status":{"type":"string","description":"`pending`, `ready`, `failed` or `expired`."}}},"Folder":{"type":"string","enum":["inbox","sent","drafts","junk","all"]},"GrantList":{"type":"object","required":["clerk_user_ids"],"properties":{"clerk_user_ids":{"type":"array","items":{"type":"string"}}}},"GrantRequest":{"type":"object","required":["clerk_user_id"],"properties":{"clerk_user_id":{"type":"string"}}},"HandledRequest":{"type":"object","required":["handled"],"properties":{"handled":{"type":"boolean"}}},"MailboxList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxView"}}}},"MailboxView":{"type":"object","required":["id","domain_id","address","display_name","status","aliases","used_bytes","unread_count","created_at"],"properties":{"address":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"display_name":{"type":"string"},"domain_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"`active` or `suspended`."},"unread_count":{"type":"integer","format":"int64","description":"Unread messages in the mailbox's inbox folder."},"used_bytes":{"type":"integer","format":"int64"}}},"MeResponse":{"type":"object","required":["organization_id","actor","scopes","restriction","plan","usage","postyard"],"properties":{"actor":{"$ref":"#/components/schemas/ActorView"},"organization_id":{"type":"string","format":"uuid"},"plan":{"$ref":"#/components/schemas/PlanView"},"postyard":{"$ref":"#/components/schemas/PostyardAddresses"},"restriction":{"type":"object","description":"`{\"type\":\"all\"}`, `{\"type\":\"domains\",\"ids\":[..]}` or `{\"type\":\"mailboxes\",\"ids\":[..]}`."},"scopes":{"type":"array","items":{"type":"string"},"description":"Scope names such as `mail.read`."},"usage":{"$ref":"#/components/schemas/UsageView"}}},"MessageDetail":{"type":"object","required":["message","attachments"],"properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentView"}},"html":{"type":["string","null"],"description":"Raw, unsanitized HTML from the sender: never render it. With `display=1` it is the document prepared for display."},"html_too_large":{"type":"boolean","description":"Only with `display=1`: the HTML part was too large to prepare for display, so `html` is\n`null` and clients show `text`."},"message":{"$ref":"#/components/schemas/MessageView"},"text":{"type":["string","null"]},"text_is_preview":{"type":"boolean","description":"`text` is the message preview standing in for a missing text part, not the body."}}},"MessageView":{"type":"object","required":["id","conversation_id","mailbox_id","direction","folder","to","cc","reply_to","subject","preview","received_at","is_read","is_handled","has_attachments"],"properties":{"cc":{"type":"array","items":{"type":"string"}},"conversation_id":{"type":"string","format":"uuid"},"direction":{"type":"string","description":"`inbound`, `outbound` or `draft`."},"folder":{"type":"string"},"from":{"type":["string","null"]},"has_attachments":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"is_handled":{"type":"boolean"},"is_read":{"type":"boolean"},"mailbox_id":{"type":"string","format":"uuid"},"preview":{"type":"string"},"received_at":{"type":"string","format":"date-time"},"reply_to":{"type":"array","items":{"type":"string"},"description":"The original's Reply-To addresses: a reply goes to these instead of `from`."},"subject":{"type":"string"},"to":{"type":"array","items":{"type":"string"}}}},"PlanView":{"type":"object","required":["key","name","domain_limit"],"properties":{"domain_limit":{"type":"integer","format":"int64"},"key":{"type":"string","description":"`pro`, `pro_50` or `pro_100`."},"name":{"type":"string"}}},"PostyardAddresses":{"type":"object","description":"Postyard's own addresses: where the support form's requests go (`POSTYARD_SUPPORT_TO`) and\nthe sender of every Postyard notice and support request (`POSTYARD_NOTIFY_FROM`).","required":["support","notifier"],"properties":{"notifier":{"type":"string"},"support":{"type":"string"}}},"PresetName":{"type":"string","enum":["read_draft","read_draft_send","admin"]},"ReadRequest":{"type":"object","required":["read"],"properties":{"read":{"type":"boolean"}}},"RecipientStatus":{"type":"object","required":["address","status"],"properties":{"address":{"type":"string"},"status":{"type":"string"}}},"RecordRow":{"type":"object","required":["key","kind","host","value","requirement","explanation","status","observed","reason"],"properties":{"checked_at":{"type":["string","null"],"format":"date-time"},"explanation":{"type":"string"},"fix":{"type":["string","null"],"description":"The record to publish, when the check is not passing."},"host":{"type":"string"},"key":{"type":"string","description":"`ownership`, `mx`, `spf`, `dkim1`..`dkim3` or `dmarc`."},"kind":{"type":"string","description":"`mx`, `txt` or `cname`."},"observed":{"type":"array","items":{"type":"string"}},"priority":{"type":["integer","null"],"format":"int32","minimum":0},"reason":{"type":"string"},"requirement":{"type":"string","description":"`ownership`, `receive`, `send` or `recommended`."},"status":{"type":"string","description":"`pass`, `fail`, `warn` or `unknown`."},"value":{"type":"string"}}},"ReplyInput":{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/UploadedAttachment"}},"override_to":{"type":["array","null"],"items":{"type":"string"},"description":"Replaces the derived `To` recipients. Needs the send scope."},"reply_all":{"type":"boolean","description":"Also address everyone else on the original message."},"text":{"type":"string"}}},"RequestLogPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RequestLogView"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` on the last page."}}},"RequestLogView":{"type":"object","required":["id","created_at","method","route","status","duration_ms","request_id"],"properties":{"actor_type":{"type":["string","null"],"description":"`member`, `api_key` or `oauth`."},"created_at":{"type":"string","format":"date-time"},"credential_id":{"type":["string","null"],"format":"uuid"},"duration_ms":{"type":"integer","format":"int32"},"error_code":{"type":["string","null"]},"id":{"type":"integer","format":"int64"},"method":{"type":"string"},"request_id":{"type":"string"},"route":{"type":"string","description":"The route template (`/v1/mailboxes/{id}`), never the raw path. Every MCP tool call\nshares `/mcp`."},"status":{"type":"integer","format":"int32"}}},"RotatedSecret":{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","description":"Shown only once. The previous secret keeps signing for 24 hours."}}},"SendDetail":{"type":"object","required":["send","history"],"properties":{"history":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryEventView"}},"send":{"$ref":"#/components/schemas/SendView"}}},"SendPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SendView"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` on the last page."}}},"SendView":{"type":"object","required":["id","mailbox_id","message_id_header","subject","created_at","recipients"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"mailbox_id":{"type":"string","format":"uuid"},"message_id_header":{"type":"string"},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/RecipientStatus"}},"subject":{"type":"string"}}},"SetupStatus":{"type":"object","required":["has_domain","domain_verified","has_mailbox","sent_ok","received_ok","agent_connected"],"properties":{"agent_connected":{"type":"boolean","description":"An API key or OAuth connection has been used."},"domain_verified":{"type":"boolean","description":"At least one domain has its ownership verified."},"has_domain":{"type":"boolean","description":"The organization has at least one domain."},"has_mailbox":{"type":"boolean"},"received_ok":{"type":"boolean","description":"At least one inbound message was received."},"sent_ok":{"type":"boolean","description":"A send reached `accepted`, `delivered` or `local` (a mailbox on this server) for at least\none recipient. Still true once that send has aged out of the history."}}},"SupportReceipt":{"type":"object","required":["reference"],"properties":{"reference":{"type":"string","description":"`PY-<n>`: quoted in the email to support, so a later message can refer to it."}}},"SupportRequest":{"type":"object","required":["topic","subject","message"],"properties":{"about":{"type":["string","null"],"description":"A domain name or mailbox address of your organization the request is about. A member may\nname only a mailbox they have access to."},"include_diagnostics":{"type":"boolean","description":"Adds the organization's usage, the state of `about` and its last 10 failed deliveries\n(recipient, status and SMTP codes; never mail content or keys)."},"message":{"type":"string","description":"1 to 10,000 characters."},"subject":{"type":"string","description":"1 to 200 characters, on one line."},"topic":{"$ref":"#/components/schemas/Topic"}}},"SuppressionList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SuppressionView"}}}},"SuppressionView":{"type":"object","required":["address","reason","created_at"],"properties":{"address":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"reason":{"type":"string","description":"`hard_bounce`, `complaint` or `manual`."}}},"Topic":{"type":"string","enum":["dns","sending","agents","billing","other"]},"UpdateConnectionRequest":{"type":"object","properties":{"preset":{"oneOf":[{"$ref":"#/components/schemas/PresetName","description":"`read_draft`, `read_draft_send` or `admin`. Omit to keep the current scopes."},{"type":"null"}]},"restriction":{"type":["object","null"],"description":"Omit to keep the current restriction."}}},"UpdateMailboxRequest":{"type":"object","properties":{"display_name":{"type":["string","null"]},"suspended":{"type":["boolean","null"]}}},"UploadForm":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file to attach, at most 17 MB."}}},"UploadedAttachment":{"type":"object","required":["id","name","content_type"],"properties":{"content_type":{"type":"string"},"id":{"type":"string","description":"The blob id returned by the upload."},"name":{"type":"string"}}},"UsageReport":{"type":"object","required":["period_start","period_end","outbound_recipients_used","outbound_recipients_limit","storage_used_bytes","storage_limit_bytes","domains","domains_limit","mailboxes","mailboxes_limit"],"properties":{"domains":{"type":"integer","format":"int64"},"domains_limit":{"type":"integer","format":"int64"},"mailboxes":{"type":"integer","format":"int64"},"mailboxes_limit":{"type":"integer","format":"int64"},"outbound_recipients_limit":{"type":"integer","format":"int64"},"outbound_recipients_used":{"type":"integer","format":"int64"},"period_end":{"type":"string","format":"date-time"},"period_start":{"type":"string","format":"date-time"},"storage_limit_bytes":{"type":"integer","format":"int64"},"storage_used_bytes":{"type":"integer","format":"int64"}}},"UsageView":{"type":"object","required":["domains"],"properties":{"domains":{"type":"integer","format":"int64"}}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}}}