{ "openapi": "3.1.0", "info": { "title": "Pidgeon API", "version": "1.0.0", "description": "An email inbox API for AI agents. Inboxes your code creates in one call, threads that carry state, and sending from a domain you own.\n\nEvery response is `{ data }`, a page is `{ data, has_more, next_cursor }`, and a failure is `{ error: { code, message } }`. There is no third envelope." }, "servers": [ { "url": "https://pidgeon.ai/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "schemas": { "Address": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "additionalProperties": false, "description": "A mailbox, with the display name when one was given." }, "Attachment": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "downloadable": { "type": "boolean", "description": "False when there is metadata but no object store behind it." } }, "required": [ "id", "filename", "content_type", "size", "downloadable" ], "additionalProperties": false }, "AgentSignup": { "type": "object", "properties": { "signup_id": { "type": "string" }, "address": { "type": "string" }, "identity_id": { "type": "string" }, "can_send": { "type": "boolean", "const": false }, "code_expires_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] } }, "required": [ "signup_id", "address", "identity_id", "can_send", "code_expires_at" ], "additionalProperties": false }, "Sent": { "type": "object", "properties": { "id": { "type": "string" }, "thread_id": { "type": "string" }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "address", "reason" ], "additionalProperties": false } } }, "required": [ "id", "thread_id", "rejected" ], "additionalProperties": false }, "AgentVerified": { "type": "object", "properties": { "address": { "type": "string" }, "identity_id": { "type": "string" }, "sign_in_url": { "type": "string" } }, "required": [ "address", "identity_id", "sign_in_url" ], "additionalProperties": false }, "Identity": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "local_part": { "type": "string" }, "domain": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "description": "human, team, application, workflow or agent." }, "mode": { "type": "string", "description": "Who answers: human, automated or hybrid." }, "status": { "type": "string" }, "capabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean" } }, "has_inbox": { "type": "boolean", "description": "False for an address that turns mail into events and stores nothing." }, "routed_address_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string", "description": "ISO-8601, UTC." }, "expires_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ], "description": "When it stops accepting mail. Expiry suspends the address; it never deletes it." }, "send_policy": { "type": "string", "description": "Who it may write to: open, reply_only (somebody who wrote to it first), or list." }, "tenant_id": { "description": "Your own opaque grouping for this address. Never parsed here.", "type": [ "string", "null" ] } }, "required": [ "id", "email", "local_part", "domain", "display_name", "type", "mode", "status", "capabilities", "has_inbox", "routed_address_count", "created_at", "expires_at", "send_policy", "tenant_id" ], "additionalProperties": false }, "Message": { "type": "object", "properties": { "id": { "type": "string" }, "thread_id": { "type": "string" }, "identity": { "type": [ "string", "null" ] }, "direction": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "additionalProperties": false, "description": "A mailbox, with the display name when one was given." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "additionalProperties": false, "description": "A mailbox, with the display name when one was given." } }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "additionalProperties": false, "description": "A mailbox, with the display name when one was given." } }, "subject": { "type": [ "string", "null" ] }, "delivered_to": { "description": "The envelope recipient, which is not always in `to`.", "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "html": { "type": "string", "description": "Sanitised server-side: our policy travels with the content." }, "reply_html": { "type": "string", "description": "`html` with the quoted history taken off: what the sender wrote this time." }, "quoted_html": { "description": "The history the reply quoted, or null when there was nothing to fold.", "type": [ "string", "null" ] }, "reply_text": { "type": "string", "description": "The reply as plain text. `text` is the message’s own text part, quote and all." }, "is_read": { "type": "boolean" }, "is_spam": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "downloadable": { "type": "boolean", "description": "False when there is metadata but no object store behind it." } }, "required": [ "id", "filename", "content_type", "size", "downloadable" ], "additionalProperties": false } }, "invitation": { "anyOf": [ { "type": "object", "properties": { "method": { "type": [ "string", "null" ] }, "uid": { "type": "string" }, "sequence": { "type": "number" }, "status": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "start": { "description": "The local wall time the sender wrote. This and `timezone` are the truth.", "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] }, "starts_at": { "description": "The same moment as a UTC instant.", "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "all_day": { "type": "boolean" }, "timezone": { "type": [ "string", "null" ] }, "organizer_email": { "type": [ "string", "null" ] }, "organizer_name": { "type": [ "string", "null" ] }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "optional": { "type": "boolean" }, "rsvp": { "type": "boolean" } }, "required": [ "email", "name", "status", "optional", "rsvp" ], "additionalProperties": false } }, "recurrence_rule": { "type": [ "string", "null" ] }, "is_instance": { "type": "boolean" } }, "required": [ "method", "uid", "sequence", "status", "summary", "description", "location", "start", "end", "starts_at", "ends_at", "all_day", "timezone", "organizer_email", "organizer_name", "attendees", "recurrence_rule", "is_instance" ], "additionalProperties": false }, { "type": "null" } ], "description": "The calendar part this message carried, or null. See `prd/calendar.md`." }, "calendar_event_id": { "description": "The event the calendar made of that invitation, or null. A different fact from `invitation`: that is what the mail said, this is what the calendar now holds — a meeting later moved still reports the time this message invited you to.", "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "thread_id", "identity", "direction", "from", "to", "cc", "subject", "delivered_to", "text", "html", "reply_html", "quoted_html", "reply_text", "is_read", "is_spam", "attachments", "invitation", "calendar_event_id", "created_at" ], "additionalProperties": false }, "Thread": { "type": "object", "properties": { "id": { "type": "string" }, "identity": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "waiting", "resolved", "human_review" ] }, "owner_type": { "type": "string", "enum": [ "human", "automation", "agent" ] }, "assignee_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "assigned_at": { "type": [ "string", "null" ] }, "message_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_message_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "identity", "subject", "status", "owner_type", "assignee_id", "assigned_at", "message_count", "last_message_at", "created_at" ], "additionalProperties": false }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "identity": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "consecutive_failures": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_delivered_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "last_failed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "url", "identity", "event_types", "status", "consecutive_failures", "last_delivered_at", "last_failed_at", "created_at" ], "additionalProperties": false }, "WebhookCreated": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "identity": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "consecutive_failures": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_delivered_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "last_failed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." }, "secret": { "type": "string", "description": "Shown once, here, and never again." } }, "required": [ "id", "url", "identity", "event_types", "status", "consecutive_failures", "last_delivered_at", "last_failed_at", "created_at", "secret" ], "additionalProperties": false }, "Draft": { "type": "object", "properties": { "id": { "type": "string" }, "identity": { "type": [ "string", "null" ] }, "identity_id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "thread_id": { "type": [ "string", "null" ] }, "send_at": { "type": [ "string", "null" ] }, "failed_reason": { "type": [ "string", "null" ] }, "saved_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "downloadable": { "type": "boolean", "description": "False when there is metadata but no object store behind it." } }, "required": [ "id", "filename", "content_type", "size", "downloadable" ], "additionalProperties": false } } }, "required": [ "id", "identity", "identity_id", "from", "to", "cc", "bcc", "subject", "text", "thread_id", "send_at", "failed_reason", "saved_at", "created_at", "attachments" ], "additionalProperties": false }, "Calendar": { "type": "object", "properties": { "identity_id": { "type": "string" }, "identity": { "type": "string" }, "timezone": { "type": "string" }, "event_count": { "type": "number" }, "etag": { "type": "string" }, "created_at": { "type": "string", "description": "ISO-8601, UTC." }, "updated_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "identity_id", "identity", "timezone", "event_count", "etag", "created_at", "updated_at" ], "additionalProperties": false }, "CalendarEvent": { "type": "object", "properties": { "id": { "type": "string" }, "identity_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "single", "series", "instance" ] }, "series_id": { "type": [ "string", "null" ] }, "original_start": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "api", "email" ] }, "uid": { "type": "string" }, "sequence": { "type": "number" }, "status": { "type": "string", "enum": [ "confirmed", "tentative", "cancelled" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "metadata": {}, "all_day": { "type": "boolean" }, "start": { "type": "string", "description": "Local wall time in `timezone`. This is the truth." }, "end": { "type": "string", "description": "For an all-day event, the last day, inclusive." }, "timezone": { "type": "string" }, "starts_at": { "type": "string", "description": "The same moment as an instant, derived from `start`." }, "ends_at": { "type": "string", "description": "ISO-8601, UTC." }, "duration_mode": { "type": "string", "enum": [ "nominal", "exact" ] }, "duration_value": { "type": "number" }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "rule": { "type": "string", "description": "Normalised, so it may differ from what you sent." }, "exdates": { "type": "array", "items": { "type": "string" } }, "rdates": { "type": "array", "items": { "type": "string" } }, "truncate_before": { "type": [ "string", "null" ] } }, "required": [ "rule", "exdates", "rdates", "truncate_before" ], "additionalProperties": false }, { "type": "null" } ] }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "optional": { "type": "boolean" } }, "required": [ "email", "name", "status", "optional" ], "additionalProperties": false } }, "attendee_count": { "type": "number" }, "organizer_email": { "type": [ "string", "null" ] }, "origin_message_id": { "type": [ "string", "null" ] }, "etag": { "type": "string", "description": "Send it back in `If-Match` to make a write conditional." }, "created_at": { "type": "string", "description": "ISO-8601, UTC." }, "updated_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "identity_id", "kind", "series_id", "original_start", "source", "uid", "sequence", "status", "title", "description", "location", "metadata", "all_day", "start", "end", "timezone", "starts_at", "ends_at", "duration_mode", "duration_value", "recurrence", "attendees", "attendee_count", "organizer_email", "origin_message_id", "etag", "created_at", "updated_at" ], "additionalProperties": false }, "Invitation": { "type": "object", "properties": { "method": { "type": [ "string", "null" ] }, "uid": { "type": "string" }, "sequence": { "type": "number" }, "status": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "start": { "description": "The local wall time the sender wrote. This and `timezone` are the truth.", "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] }, "starts_at": { "description": "The same moment as a UTC instant.", "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "all_day": { "type": "boolean" }, "timezone": { "type": [ "string", "null" ] }, "organizer_email": { "type": [ "string", "null" ] }, "organizer_name": { "type": [ "string", "null" ] }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "optional": { "type": "boolean" }, "rsvp": { "type": "boolean" } }, "required": [ "email", "name", "status", "optional", "rsvp" ], "additionalProperties": false } }, "recurrence_rule": { "type": [ "string", "null" ] }, "is_instance": { "type": "boolean" } }, "required": [ "method", "uid", "sequence", "status", "summary", "description", "location", "start", "end", "starts_at", "ends_at", "all_day", "timezone", "organizer_email", "organizer_name", "attendees", "recurrence_rule", "is_instance" ], "additionalProperties": false }, "EventResponse": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string" }, "identity_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "single", "series", "instance" ] }, "series_id": { "type": [ "string", "null" ] }, "original_start": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "api", "email" ] }, "uid": { "type": "string" }, "sequence": { "type": "number" }, "status": { "type": "string", "enum": [ "confirmed", "tentative", "cancelled" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "metadata": {}, "all_day": { "type": "boolean" }, "start": { "type": "string", "description": "Local wall time in `timezone`. This is the truth." }, "end": { "type": "string", "description": "For an all-day event, the last day, inclusive." }, "timezone": { "type": "string" }, "starts_at": { "type": "string", "description": "The same moment as an instant, derived from `start`." }, "ends_at": { "type": "string", "description": "ISO-8601, UTC." }, "duration_mode": { "type": "string", "enum": [ "nominal", "exact" ] }, "duration_value": { "type": "number" }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "rule": { "type": "string", "description": "Normalised, so it may differ from what you sent." }, "exdates": { "type": "array", "items": { "type": "string" } }, "rdates": { "type": "array", "items": { "type": "string" } }, "truncate_before": { "type": [ "string", "null" ] } }, "required": [ "rule", "exdates", "rdates", "truncate_before" ], "additionalProperties": false }, { "type": "null" } ] }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "optional": { "type": "boolean" } }, "required": [ "email", "name", "status", "optional" ], "additionalProperties": false } }, "attendee_count": { "type": "number" }, "organizer_email": { "type": [ "string", "null" ] }, "origin_message_id": { "type": [ "string", "null" ] }, "etag": { "type": "string", "description": "Send it back in `If-Match` to make a write conditional." }, "created_at": { "type": "string", "description": "ISO-8601, UTC." }, "updated_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "identity_id", "kind", "series_id", "original_start", "source", "uid", "sequence", "status", "title", "description", "location", "metadata", "all_day", "start", "end", "timezone", "starts_at", "ends_at", "duration_mode", "duration_value", "recurrence", "attendees", "attendee_count", "organizer_email", "origin_message_id", "etag", "created_at", "updated_at" ], "additionalProperties": false }, "attendee": { "type": "string", "description": "Which of the mailbox’s addresses answered." }, "status": { "type": "string" }, "reply_sent": { "type": "boolean", "description": "Whether an iCalendar REPLY actually went to an organiser. False when the meeting has none to tell, when `send_reply` was false, and when this answer had already gone out." } }, "required": [ "event", "attendee", "status", "reply_sent" ], "additionalProperties": false }, "InvitationResponse": { "type": "object", "properties": { "status": { "type": "string" }, "attendee": { "type": "string", "description": "Which of the mailbox’s addresses answered." }, "already_sent": { "type": "boolean", "description": "True when this answer had already gone out. Not an error — a retry." }, "message_id": { "type": [ "string", "null" ] }, "thread_id": { "type": [ "string", "null" ] } }, "required": [ "status", "attendee", "already_sent", "message_id", "thread_id" ], "additionalProperties": false }, "SetupLink": { "type": "object", "properties": { "supported": { "type": "boolean" }, "provider_name": { "description": "The DNS provider’s own name, for a button label. Null when it is not known.", "type": [ "string", "null" ] }, "url": { "description": "The signed Domain Connect apply URL, at the domain’s DNS provider. Open it in a browser: the owner signs in, reviews the records and approves. Null when unsupported.", "type": [ "string", "null" ] }, "width": { "description": "The popup size the provider asks for, when it states one.", "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "provider", "unconfigured" ] }, { "type": "null" } ], "description": "`provider` — that zone’s DNS provider does not support Domain Connect, which is the common case. `unconfigured` — it does, and this deployment is not registered as a service provider, which is ours to fix. Null when `supported` is true." } }, "required": [ "supported", "provider_name", "url", "width", "height", "reason" ], "additionalProperties": false }, "Metrics": { "type": "object", "properties": { "since": { "type": "string" }, "until": { "type": "string" }, "days": { "type": "number" }, "identity": { "type": [ "string", "null" ] }, "outbound": { "type": "object", "properties": { "sent": { "type": "number" }, "delivered": { "type": "number" }, "bounced": { "type": "number" }, "rejected": { "type": "number" }, "complained": { "type": "number" }, "delivery_rate": { "type": [ "number", "null" ] } }, "required": [ "sent", "delivered", "bounced", "rejected", "complained", "delivery_rate" ], "additionalProperties": false }, "inbound": { "type": "object", "properties": { "received": { "type": "number" }, "spam": { "type": "number" } }, "required": [ "received", "spam" ], "additionalProperties": false } }, "required": [ "since", "until", "days", "identity", "outbound", "inbound" ], "additionalProperties": false }, "WebhookHeaders": { "type": "object", "properties": { "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "headers" ], "additionalProperties": false }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "identity": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "thread_id": { "type": [ "string", "null" ] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "type", "identity", "message_id", "thread_id", "data", "created_at" ], "additionalProperties": false }, "Domain": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string" }, "catch_all_enabled": { "type": "boolean" }, "identity_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "verified_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "domain", "status", "catch_all_enabled", "identity_count", "verified_at", "created_at" ], "additionalProperties": false }, "DomainDetail": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string" }, "catch_all_enabled": { "type": "boolean" }, "identity_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "verified_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." }, "dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "record_type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "priority": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "connected", "waiting", "incorrect", "not_required" ] }, "found": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "checked_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] } }, "required": [ "type", "record_type", "name", "value", "priority", "status", "found", "description", "checked_at" ], "additionalProperties": false } }, "dns_complete": { "type": "boolean" } }, "required": [ "id", "domain", "status", "catch_all_enabled", "identity_count", "verified_at", "created_at", "dns_records", "dns_complete" ], "additionalProperties": false }, "DnsRecord": { "type": "object", "properties": { "type": { "type": "string" }, "record_type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "priority": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "connected", "waiting", "incorrect", "not_required" ] }, "found": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "checked_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] } }, "required": [ "type", "record_type", "name", "value", "priority", "status", "found", "description", "checked_at" ], "additionalProperties": false }, "Verification": { "type": "object", "properties": { "verified": { "type": "boolean" }, "mail_configured": { "type": "boolean" }, "message": { "type": "string" }, "dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "record_type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "priority": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "connected", "waiting", "incorrect", "not_required" ] }, "found": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "checked_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] } }, "required": [ "type", "record_type", "name", "value", "priority", "status", "found", "description", "checked_at" ], "additionalProperties": false } }, "dns_complete": { "type": "boolean" } }, "required": [ "verified", "mail_configured", "message", "dns_records", "dns_complete" ], "additionalProperties": false }, "RoutingRule": { "type": "object", "properties": { "id": { "type": "string" }, "match": { "type": "string" }, "match_type": { "type": "string", "enum": [ "address", "catch_all", "pattern" ] }, "destination_type": { "type": "string", "enum": [ "identity", "webhook" ] }, "destination": { "type": "string" }, "destination_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "domain": { "type": "string" }, "domain_id": { "type": "string" }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "match", "match_type", "destination_type", "destination", "destination_id", "status", "domain", "domain_id", "created_at" ], "additionalProperties": false }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "response_status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." }, "delivered_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Round trip of the last attempt. Null before one, and for a refusal." }, "next_attempt_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ], "description": "When it will be tried again. Null unless it is pending with an attempt behind it." } }, "required": [ "id", "event_id", "event_type", "status", "attempts", "response_status", "error", "created_at", "delivered_at", "duration_ms", "next_attempt_at" ], "additionalProperties": false }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "identity_ids": { "type": "array", "items": { "type": "string" } }, "access": { "type": "string", "enum": [ "read", "send", "admin" ], "description": "The highest rung on any address. Composed with the grant; lower wins." }, "created_by_key_id": { "type": [ "string", "null" ] }, "last_used_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "name", "prefix", "identity_ids", "access", "created_by_key_id", "last_used_at", "revoked_at", "created_at" ], "additionalProperties": false }, "AppPassword": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "ISO-8601, UTC." }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "name", "prefix", "last_used_at", "revoked_at", "created_at" ], "additionalProperties": false }, "Workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "name", "plan", "status" ], "additionalProperties": false }, "Deleted": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "Emptied": { "type": "object", "properties": { "folder": { "type": "string" }, "deleted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "folder", "deleted" ], "additionalProperties": false }, "Replayed": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "const": "pending" } }, "required": [ "id", "status" ], "additionalProperties": false }, "Mailbox": { "type": "object", "properties": { "folder": { "type": "string", "enum": [ "inbox", "starred", "sent", "drafts", "scheduled", "snoozed", "archive", "spam", "trash" ] }, "total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Null where the product does not count that folder. Not zero — zero is a claim." }, "unread": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "folder", "total", "unread" ], "additionalProperties": false }, "UploadedAttachment": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "filename", "content_type", "size" ], "additionalProperties": false }, "MailboxChange": { "type": "object", "properties": { "id": { "type": "string" }, "changed_at": { "type": "string", "description": "ISO-8601, UTC." }, "deleted": { "type": "boolean" }, "folder": { "type": [ "string", "null" ] } }, "required": [ "id", "changed_at", "deleted" ], "additionalProperties": false }, "Restored": { "type": "object", "properties": { "restored": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "restored" ], "additionalProperties": false }, "Undo": { "type": "object", "properties": { "id": { "type": "string" }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "undo": { "type": "array", "items": {} } }, "required": [ "undo" ], "additionalProperties": false }, "MessageListItem": { "type": "object", "properties": { "id": { "type": "string" }, "thread_id": { "type": "string" }, "direction": { "type": "string" }, "from": { "type": "string", "description": "Who the row is about: the sender in inbox, the recipient in sent." }, "from_name": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "preview": { "type": [ "string", "null" ] }, "is_read": { "type": "boolean" }, "is_starred": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "is_spam": { "type": "boolean" }, "has_attachments": { "type": "boolean" }, "attachment_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "message_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "assignee_id": { "type": [ "string", "null" ] }, "timestamp": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "thread_id", "direction", "from", "from_name", "subject", "preview", "is_read", "is_starred", "is_draft", "is_spam", "has_attachments", "attachment_count", "message_count", "assignee_id", "timestamp" ], "additionalProperties": false }, "Member": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "joined_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "email", "name", "role", "joined_at" ], "additionalProperties": false }, "MailboxAccess": { "type": "object", "properties": { "identity_id": { "type": "string" }, "owner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "The person the address is. Null for a shared or programmable one." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The grant’s own id. What `DELETE ?grant_id=` takes." }, "kind": { "type": "string", "enum": [ "everyone", "member", "key" ] }, "principal_id": { "description": "The person or key. Null for `everyone`, which names nobody.", "type": [ "string", "null" ] }, "label": { "type": "string", "description": "For showing a person. A renamed key changes it; never match on it." }, "access": { "type": "string", "enum": [ "read", "send", "admin" ] } }, "required": [ "id", "kind", "principal_id", "label", "access" ], "additionalProperties": false } }, "can_manage": { "type": "boolean", "description": "Whether this credential may change any of the above." } }, "required": [ "identity_id", "owner", "entries", "can_manage" ], "additionalProperties": false }, "TenantSuspended": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "suspended": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many addresses this call changed." } }, "required": [ "tenant_id", "suspended" ], "additionalProperties": false }, "ReceiveRules": { "type": "object", "properties": { "identity_id": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "description": "reject refuses before the message is stored. spam, trash and archive file it. inbox means never classify this sender as spam." }, "match_type": { "type": "string", "enum": [ "address", "domain" ] }, "match_value": { "type": "string" }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "action", "match_type", "match_value", "created_at" ], "additionalProperties": false } } }, "required": [ "identity_id", "rules" ], "additionalProperties": false }, "ReceiveRuleRemoved": { "type": "object", "properties": { "identity_id": { "type": "string" }, "rule_id": { "type": "string" }, "removed": { "type": "boolean" } }, "required": [ "identity_id", "rule_id", "removed" ], "additionalProperties": false }, "SendRules": { "type": "object", "properties": { "identity_id": { "type": "string" }, "send_policy": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "effect": { "type": "string", "description": "allow or block. A block refuses under every policy." }, "match_type": { "type": "string", "enum": [ "address", "domain" ] }, "match_value": { "type": "string" }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "effect", "match_type", "match_value", "created_at" ], "additionalProperties": false } } }, "required": [ "identity_id", "send_policy", "rules" ], "additionalProperties": false }, "SendRuleRemoved": { "type": "object", "properties": { "identity_id": { "type": "string" }, "rule_id": { "type": "string" }, "removed": { "type": "boolean" } }, "required": [ "identity_id", "rule_id", "removed" ], "additionalProperties": false }, "Revoked": { "type": "object", "properties": { "identity_id": { "type": "string" }, "grant_id": { "type": "string" }, "revoked": { "type": "boolean" } }, "required": [ "identity_id", "grant_id", "revoked" ], "additionalProperties": false }, "Label": { "type": "object", "properties": { "id": { "type": "string" }, "identity_id": { "type": "string" }, "name": { "type": "string" }, "colour": { "type": "string" }, "created_at": { "type": "string", "description": "ISO-8601, UTC." } }, "required": [ "id", "identity_id", "name", "colour", "created_at" ], "additionalProperties": false }, "LabelRemoved": { "type": "object", "properties": { "thread_id": { "type": "string" }, "label_id": { "type": "string" }, "removed": { "type": "boolean" } }, "required": [ "thread_id", "label_id", "removed" ], "additionalProperties": false }, "AttachmentUrl": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "description": "Short-lived and signed. It expires; do not store it." } }, "required": [ "id", "url" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "description": "Written for a person, and safe to show one." }, "field": { "description": "Present when one input was at fault.", "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key, as `Authorization: Bearer pk_…`. Keys are scoped to one account and are shown once when created." } } }, "paths": { "/agent/signup": { "post": { "operationId": "agentSignUp", "summary": "Sign an agent up", "description": "The one call in this API that needs no key. An agent names a username and, optionally, the human who will own the mailbox; a six-digit code goes to that human and **nothing is created until it comes back**. Without a `human_email` the name is reserved and dormant — attach one with `POST /agent/human`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 2, "maxLength": 64 }, "human_email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "source": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } }, "required": [ "username", "human_email" ] } } } }, "responses": { "201": { "description": "The pending signup.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentSignup" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "tags": [ "agent" ] } }, "/agent/human": { "post": { "operationId": "agentAttachHuman", "summary": "Name the human for a signup", "description": "For a signup that named none. Sends a fresh code and restarts the clock.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signup_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "human_email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "signup_id", "human_email" ] } } } }, "responses": { "200": { "description": "The pending signup.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentSignup" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "tags": [ "agent" ] } }, "/agent/verify": { "post": { "operationId": "agentVerify", "summary": "Verify an agent with the human’s code", "description": "Creates the account and the address. Ten wrong codes spend the signup, whatever comes next. It returns no key: the agent asks for one through the account it now belongs to, which is how every other key is made.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signup_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "signup_id", "code" ] } } } }, "responses": { "200": { "description": "The address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentVerified" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "tags": [ "agent" ] } }, "/identities": { "get": { "operationId": "identitiesList", "summary": "List addresses", "description": "Alphabetical by address. `cursor` is the last address on the page before it, not a timestamp — this is the one list that is not ordered by time, because it is read by somebody looking for a particular address.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "A page of addresses.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "post": { "operationId": "identitiesCreate", "summary": "Create an address", "description": "Idempotent with an `Idempotency-Key` header: the same key returns the first result rather than creating a second address.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "local_part": { "type": "string", "minLength": 1, "maxLength": 64 }, "display_name": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "type": { "default": "application", "type": "string", "enum": [ "human", "team", "application", "workflow", "agent" ] }, "mode": { "type": "string", "enum": [ "human", "automated", "hybrid" ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "send_policy": { "type": "string", "enum": [ "open", "reply_only", "list" ] }, "tenant_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "domain_id", "local_part" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Identity" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] } }, "/identities/{id}": { "get": { "operationId": "identitiesGet", "summary": "Fetch one address", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Identity" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "patch": { "operationId": "identitiesUpdate", "summary": "Update an address", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "human", "automated", "hybrid" ] }, "capabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean" } }, "status": { "type": "string", "enum": [ "active", "suspended", "archived" ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "send_policy": { "type": "string", "enum": [ "open", "reply_only", "list" ] }, "tenant_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Identity" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "delete": { "operationId": "identitiesDelete", "summary": "Delete an address", "description": "Takes its messages, routing rules and webhooks with it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] } }, "/identities/{id}/access": { "get": { "operationId": "identitiesAccessGet", "summary": "Who can reach this address", "description": "Reading the list requires being able to reach the address: who has access to somebody’s mailbox is itself private.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The access list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailboxAccess" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "post": { "operationId": "identitiesAccessCreate", "summary": "Grant access", "description": "Name exactly one of `user_id`, `api_key_id` or `everyone`. Granting **replaces** any grant that principal already had, so calling this twice changes the rung rather than leaving two answers behind. Answers 404 rather than 403 when you may not administer the address — including when you can read it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "api_key_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "everyone": { "type": "boolean", "const": true }, "access": { "type": "string", "enum": [ "read", "send", "admin" ] } }, "required": [ "access" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The access list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailboxAccess" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "delete": { "operationId": "identitiesAccessDelete", "summary": "Revoke access", "description": "By the grant’s own id, which `GET` returned as `id`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "grant_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Revoked" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] } }, "/identities/{id}/send-rules": { "get": { "operationId": "identitiesSendRulesGet", "summary": "What this address may write to", "description": "The allow and block list, and the `send_policy` it hangs off — the rules mean nothing without it. Requires `send` on the address rather than `admin`: a caller refused a recipient has to be able to find out why.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendRules" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "post": { "operationId": "identitiesSendRulesCreate", "summary": "Allow or block a recipient", "description": "`value` is an address or a domain and the string says which: `billing@acme.com` matches one person, `acme.com` matches everybody there. **The more specific rule wins**, so blocking a domain and allowing one person at it does what it looks like. Adding **replaces** any rule already there for that value, so `allow` where `block` sat is a change of mind rather than a conflict. A `block` refuses under every policy, including `open`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "effect": { "type": "string", "enum": [ "allow", "block" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "effect", "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendRules" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "delete": { "operationId": "identitiesSendRulesDelete", "summary": "Remove a rule", "description": "By the rule’s own id, which `GET` returned as `id`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendRuleRemoved" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] } }, "/identities/{id}/receive-rules": { "get": { "operationId": "identitiesReceiveRulesGet", "summary": "Who may write to this address", "description": "The rules that decide what reaches this address. Requires `read` rather than `admin`: anybody who may read the mail may see why some of it did not arrive. **Workspace-wide rules are not listed here** — these are the address’s own, and a key that administers one address must not be able to silence a sender for every other address in the workspace.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReceiveRules" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "post": { "operationId": "identitiesReceiveRulesCreate", "summary": "Decide what happens to a sender", "description": "`value` is an address or a domain and the string says which: `billing@acme.com` matches one person, `acme.com` matches everybody there. **The more specific rule wins**, and an address’s own rule wins over a workspace-wide one. Adding **replaces** any rule already there for that value.\n\n`action` is `reject`, `spam`, `trash`, `archive` or `inbox`. **`reject` refuses before the message is stored** — no row, no thread, no storage charged and no webhook — which is what an address nobody will ever open wants. The other four file it, and `inbox` means *never classify this sender as spam*.\n\n**It is not a security control.** The `From:` header is written by the sender, and anybody blocked can change it for the price of a new address. What this buys is not paying for mail from senders who have not bothered.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "reject", "spam", "trash", "archive", "inbox" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "action", "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReceiveRules" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] }, "delete": { "operationId": "identitiesReceiveRulesDelete", "summary": "Remove a rule", "description": "By the rule’s own id, which `GET` returned as `id`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReceiveRuleRemoved" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] } }, "/tenants/{id}/suspend": { "post": { "operationId": "identitiesSuspendTenant", "summary": "Offboard one of your customers", "description": "Suspends every address carrying that `tenant_id`. **Suspends, never deletes** — the mail, the threads and the grants all stay, and each address emits `identity.suspended`. Deleting them is still one call each. Idempotent: it changes what is active and reports how many, so a retry is safe. It reaches only addresses you could have suspended one at a time.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Your own tenant id, URL-encoded." } ], "responses": { "200": { "description": "What changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TenantSuspended" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "identities" ] } }, "/labels": { "get": { "operationId": "labelsList", "summary": "List labels", "description": "The labels of one address.", "parameters": [ { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The labels.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "labels" ] }, "post": { "operationId": "labelsCreate", "summary": "Create a label", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identity_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "colour": { "type": "string" } }, "required": [ "identity_id", "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The label.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Label" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "labels" ] } }, "/labels/{id}": { "patch": { "operationId": "labelsUpdate", "summary": "Rename or recolour a label", "description": "A body with neither `name` nor `colour` is refused.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "colour": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The label.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Label" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "labels" ] }, "delete": { "operationId": "labelsDelete", "summary": "Delete a label", "description": "The label goes; the conversations it was on stay.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "labels" ] } }, "/threads/{id}/labels": { "get": { "operationId": "threadsLabelsGet", "summary": "The labels on a conversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The labels.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "threads" ] }, "post": { "operationId": "threadsLabelsCreate", "summary": "Apply a label", "description": "Answers the conversation’s whole label list, not just the one added.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "label_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The labels.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "threads" ] }, "delete": { "operationId": "threadsLabelsDelete", "summary": "Remove a label", "description": "`label_id` in the query, because a label hangs off the conversation.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "label_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LabelRemoved" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "threads" ] } }, "/messages": { "get": { "operationId": "messagesListInThread", "summary": "List messages", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "thread_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "A page of messages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] }, "post": { "operationId": "messagesSend", "summary": "Send a message", "description": "Idempotent with an `Idempotency-Key` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "to": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } } ] }, "cc": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } } ] }, "bcc": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } } ] }, "subject": { "default": "", "type": "string", "maxLength": 500 }, "text": { "default": "", "type": "string", "maxLength": 500000 }, "html": { "type": "string", "maxLength": 1000000 }, "attachment_ids": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in_reply_to": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The sent message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/messages/search": { "get": { "operationId": "messagesSearch", "summary": "Search one mailbox", "description": "Full-text, ranked by relevance, one mailbox at a time. Results carry the folder they were found in. Not paged: page two of a relevance ranking is a place nobody goes, so narrow the query instead.", "parameters": [ { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "in", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbox", "starred", "sent", "drafts", "scheduled", "snoozed", "archive", "spam", "trash" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "has_attachment", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_unread", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_starred", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "label_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "What matched.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageListItem" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/messages/actions": { "post": { "operationId": "messagesAct", "summary": "Apply one action to many conversations", "description": "Up to 200, the same cap the dashboard uses. Thread-scoped, like everything else that changes a conversation. The response carries an `undo`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "action": { "type": "string", "enum": [ "read", "unread", "star", "unstar", "archive", "unarchive", "delete", "restore", "spam", "not_spam", "delete_forever" ] } }, "required": [ "message_ids", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "What was applied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Undo" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/messages/undo": { "post": { "operationId": "messagesUndo", "summary": "Put an action back", "description": "Hand back the `undo` from a `PATCH` or a batch. Unusual for an API to have, and the argument is that software makes mistakes at a speed a person does not.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "undo": { "minItems": 1, "maxItems": 200, "type": "array", "items": {} } }, "required": [ "undo" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "How many rows went back.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Restored" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/messages/{id}": { "get": { "operationId": "messagesGet", "summary": "Fetch one message", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] }, "patch": { "operationId": "messagesUpdate", "summary": "Change one conversation", "description": "Three different kinds of fact: `is_read` is about the reader, `is_starred` is about the mailbox, and `folder` is where the conversation lives. Thread-scoped. The response carries an `undo`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_read": { "type": "boolean" }, "is_starred": { "type": "boolean" }, "folder": { "type": "string", "enum": [ "inbox", "archive", "spam", "trash" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "What changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Undo" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/messages/{id}/reply": { "post": { "operationId": "messagesReply", "summary": "Reply to one message", "description": "The recipients, the subject and the thread are read off the message being answered. You bring the words.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "default": "", "type": "string", "maxLength": 500000 }, "html": { "type": "string", "maxLength": 1000000 }, "to": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "cc": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "bcc": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "attachment_ids": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Sent" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/messages/{id}/reply-all": { "post": { "operationId": "messagesReplyAll", "summary": "Reply to everybody on one message", "description": "Every address on the message except the ones that reach this mailbox — which a caller cannot work out, because it needs the routing table.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "default": "", "type": "string", "maxLength": 500000 }, "html": { "type": "string", "maxLength": 1000000 }, "to": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "cc": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "bcc": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "attachment_ids": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Sent" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/messages/{id}/forward": { "post": { "operationId": "messagesForward", "summary": "Forward one message", "description": "`to` is required: a forward exists to reach somebody the original did not.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "default": "", "type": "string", "maxLength": 500000 }, "html": { "type": "string", "maxLength": 1000000 }, "to": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "cc": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "bcc": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "attachment_ids": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Sent" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/messages/{id}/raw": { "get": { "operationId": "messagesRaw", "summary": "The message as it arrived", "description": "`message/rfc822`, not JSON — the point is bytes nobody re-encoded. It 404s when the original has aged out of storage, which leaves a normal parsed message.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The original message.", "content": { "message/rfc822": { "schema": { "type": "string" } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/threads": { "get": { "operationId": "threadsList", "summary": "List threads", "description": "Filter with `identity_id`, `status`, `owner_type` and `assignee_id`. `assignee_id` takes a person’s id, or the literal `unassigned` for the queue nobody has picked up — it says which *human* is answering, where `owner_type` says which kind of thing is.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "A page of threads.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "threads" ] } }, "/threads/{id}": { "get": { "operationId": "threadsGet", "summary": "Read a conversation", "description": "One conversation, by id. Every event payload carries a `thread_id`, so this is how a webhook handler turns one into something it can read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The thread.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Thread" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "threads" ] }, "patch": { "operationId": "threadsUpdate", "summary": "Update a thread", "description": "Its status and who owns it — the state a conversation carries.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "waiting", "resolved", "human_review" ] }, "owner_type": { "type": "string", "enum": [ "human", "automation", "agent" ] }, "assignee_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The thread.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Thread" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "threads" ] } }, "/domains": { "get": { "operationId": "domainsList", "summary": "List domains", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "A page of domains.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "domains" ] }, "post": { "operationId": "domainsCreate", "summary": "Connect a domain", "description": "Returns the domain **and the records to publish**, because showing them to your own customer is the one thing every caller does next. DNS is the step this API cannot perform — we cannot write in somebody else’s zone — so the job is to make the human step delegable. Watch `dns_complete`: it is false while the DKIM records do not exist yet, and a list published in that state verifies and cannot sign mail.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253 } }, "required": [ "domain" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The domain and its records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DomainDetail" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "domains" ] } }, "/domains/{id}/zone-file": { "get": { "operationId": "domainsZoneFile", "summary": "The records as a zone file", "description": "BIND format, which Route 53, Cloudflare and most registrars import and our JSON is not. TTLs are 300: these records change twice, and a long TTL on one you are getting right is an hour of somebody else’s cache.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A zone file.", "content": { "text/dns": { "schema": { "type": "string" } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "domains" ] } }, "/domains/{id}/setup-link": { "get": { "operationId": "domainsGetSetupLink", "summary": "One-click DNS setup, when the provider supports it", "description": "The **Domain Connect** standard: the URL returned is signed by and points at the domain’s own DNS provider, where the owner signs in, reviews the records and approves — the provider writes them. Nothing here is a credential of ours.\n\nAnswers `200` either way. `supported: false` is a fact about somebody else’s DNS provider rather than a failure of this request, and `reason` says whose problem it is: `provider` means that zone cannot do it, `unconfigured` means this deployment is not registered. Either way, fall back to `GET /domains/{id}/zone-file` or the `records` on the domain.\n\n`template` is `mail` (everything: ownership, DKIM and MX) or `mx` (the MX alone, for a domain already sending through us that is now going to receive).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "template", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mail", "mx" ], "default": "mail" }, "description": "Which records the link should publish." } ], "responses": { "200": { "description": "Whether it can be done, and where.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SetupLink" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "domains" ] } }, "/domains/{id}/verify": { "post": { "operationId": "domainsVerify", "summary": "Check the zone again", "description": "Idempotent and safe to poll — calling it on a verified domain re-checks and says so rather than erroring. Both halves in one answer: ownership, and whether mail is configured. The floor on how often this is worth calling is the zone’s TTL. Better still, subscribe to `domain.verified` and do not poll.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Where it stands.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Verification" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "domains" ] } }, "/domains/{id}": { "get": { "operationId": "domainsGet", "summary": "Fetch one domain, with the state of each record", "description": "`dns_records[].status` says which of ownership, MX, SPF, DKIM and DMARC is missing or wrong, and `found` says what is there instead — which is the difference between your support queue and your customer fixing one TXT record.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DomainDetail" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "domains" ] }, "delete": { "operationId": "domainsDelete", "summary": "Disconnect a domain", "description": "Takes its addresses, their mail, their routing rules and their webhooks with it. There is no undo.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "domains" ] }, "patch": { "operationId": "domainsUpdate", "summary": "Turn the catch-all on or off", "description": "The one thing about a domain that can change. Catch-all is two gates: this switch, and a `catch_all` routing rule saying where the mail goes — so turning it on without a rule does nothing, and turning it off later does not throw away where the mail was going.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "catch_all_enabled": { "type": "boolean" } }, "required": [ "catch_all_enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Domain" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "domains" ] } }, "/routing-rules": { "get": { "operationId": "routingList", "summary": "List routing rules", "description": "Every rule in the workspace, newest domain-first. `domain_id` narrows it to one domain.", "parameters": [ { "name": "domain_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "A page of rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingRule" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "routing" ] }, "post": { "operationId": "routingCreate", "summary": "Route an address somewhere", "description": "An address always beats a rule, so a rule for an address that already exists is refused rather than silently ignored. Name exactly one destination: an address you could already send from, or a webhook — a webhook destination has no inbox, so the message is handed to the endpoint and then gone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "match_type": { "type": "string", "const": "address" }, "local_part": { "type": "string", "minLength": 1, "maxLength": 64 }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "destination_identity_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "destination_webhook_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "match_type", "local_part" ], "additionalProperties": false }, { "type": "object", "properties": { "match_type": { "type": "string", "const": "pattern" }, "local_part": { "type": "string", "minLength": 2, "maxLength": 64 }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "destination_identity_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "destination_webhook_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "match_type", "local_part" ], "additionalProperties": false }, { "type": "object", "properties": { "match_type": { "type": "string", "const": "catch_all" }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "destination_identity_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "destination_webhook_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "match_type", "domain_id" ], "additionalProperties": false } ] } } } }, "responses": { "201": { "description": "The rule.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoutingRule" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "routing" ] } }, "/routing-rules/{id}": { "patch": { "operationId": "routingUpdate", "summary": "Enable or disable a rule", "description": "A disabled rule still says where that address was going, which is what you want during an incident. What it matches and where it points are the rule itself and cannot be edited — create the replacement and delete this one.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The rule.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoutingRule" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "routing" ] }, "delete": { "operationId": "routingDelete", "summary": "Delete a routing rule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "routing" ] } }, "/mailboxes": { "get": { "operationId": "mailboxesList", "summary": "List the folders of one mailbox", "description": "The shape of a sidebar. `identity_id` is required — there is no cross-mailbox view, because merging the folders of several addresses would invent a mailbox nobody has.", "parameters": [ { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The folders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "mailboxes" ] } }, "/mailboxes/changes": { "get": { "operationId": "mailboxesChanges", "summary": "What changed since you last looked", "description": "Per mailbox, not per folder: a message moving from the inbox to the archive is one event, and the row says where it went. Arrivals are included, so this is the only thing to poll. `since` is the `sync_cursor` from a listing or the `next_cursor` from a previous delta — **not** a page cursor, which walks a different order and is refused rather than guessed at. A cursor older than the window in which we keep the record of what was deleted returns `410 resync`, because an empty delta would be indistinguishable from \"nothing changed\".", "parameters": [ { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Everything that happened, oldest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MailboxChange" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "mailboxes" ] } }, "/mailboxes/{folder}": { "get": { "operationId": "mailboxesListFolder", "summary": "List one folder", "description": "A row is a conversation — the newest message in each thread — not a message. Paged by an opaque `cursor`, which is the `next_cursor` of the page before it: it carries a sort key and an id together, because several messages can share a millisecond. Do not construct one.", "parameters": [ { "name": "folder", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "label_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "A page of conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageListItem" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "mailboxes" ] }, "delete": { "operationId": "mailboxesEmptyTrash", "summary": "Empty the trash", "description": "Only `trash`; every other folder refuses. Permanent, and it takes attachments and archived originals with it — there is no undo, because the snapshot `POST /messages/undo` replays is a set of column values and these rows are gone. `delete_forever` on `POST /messages/actions` does the same to a list you name, and caps at 200; this needs no ids.", "parameters": [ { "name": "folder", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "What went.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Emptied" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "mailboxes" ] } }, "/api-keys": { "get": { "operationId": "keysList", "summary": "List the keys in this workspace", "description": "Names, prefixes, what each reaches and when it was last used — never a secret. The list is what you read before revoking something.", "responses": { "200": { "description": "A page of keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "keys" ] }, "post": { "operationId": "keysCreate", "summary": "Mint a key", "description": "`identity_ids` is required and must be a subset of what the calling key already reaches: a key cannot delegate reach it does not have. The `token` is in this response and nowhere else, ever.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "identity_ids": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "access": { "type": "string", "enum": [ "read", "send", "admin" ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "name", "identity_ids" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The key, with its token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "keys" ] } }, "/api-keys/{id}": { "get": { "operationId": "keysGet", "summary": "Fetch one key", "description": "What it reaches and when it was last used. Never the secret — that is shown once at creation and nothing can produce it again.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "keys" ] }, "patch": { "operationId": "keysUpdate", "summary": "Rename a key", "description": "The only thing about a key that can change. Not its scope — a key's reach is what somebody granted when they made it, and widening that in place would let a credential already in circulation reach further than whoever issued it agreed to.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "The key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "keys" ] }, "delete": { "operationId": "keysRevoke", "summary": "Revoke a key, and everything it minted", "description": "Transitive, and that is the point: a leaked key would otherwise mint a second one and survive its own rotation. A key may revoke itself and keys it made — not a sibling, and not its parent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "keys" ] } }, "/app-passwords": { "get": { "operationId": "appPasswordsList", "summary": "List the devices that reach one address", "parameters": [ { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "A page of passwords.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppPassword" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "appPasswords" ] }, "post": { "operationId": "appPasswordsCreate", "summary": "Issue IMAP and SMTP credentials for one address", "description": "What lets you hand a customer a mailbox they can open in a mail client. Only for an address this key can already **send** from — the credential reads the inbox and sends as the address, so issuing one is handing over exactly that. `username` and `password` are returned together and are useless apart.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identity_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "identity_id", "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The credentials, once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppPassword" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "appPasswords" ] } }, "/app-passwords/{id}": { "delete": { "operationId": "appPasswordsRevoke", "summary": "Revoke an app password", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "appPasswords" ] } }, "/workspace": { "get": { "operationId": "workspaceGet", "summary": "Which account this key is for", "description": "Read-only. Renaming is a settings field and deleting takes the calling credential with it; neither belongs to a bearer token. `plan` is here so a caller can say \"your plan allows N\" rather than discovering it from a 402.", "responses": { "200": { "description": "The workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "workspace" ] } }, "/workspace/members": { "get": { "operationId": "workspaceMembers", "summary": "List the people in this workspace", "description": "Read-only, and workspace-level: a key with no mailbox grants can still read it, for the same reason it can list domains. Assigning a conversation needs an id from here. Inviting and removing people stay in the dashboard — an invitation is mail to a person, and removing somebody hands on their mailboxes.", "responses": { "200": { "description": "Everyone in the workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "workspace" ] } }, "/events": { "get": { "operationId": "eventsList", "summary": "List events", "description": "The same events a webhook delivers, readable after the fact — so a missed delivery is recoverable without replaying anything.\n\n**Two directions.** `cursor` pages backwards through history, newest first, which is what a dashboard shows. `after` tails the log forwards, oldest first, which is what a caller that cannot receive a webhook does: ask for everything since the last event you saw, act on it, and keep the last `created_at` as the next cursor. Naming both is refused — they are different reads.\n\nA forward page is ordered oldest first precisely so its **last** row is the high-water mark to resume from; `next_cursor` is that row either way.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "identity_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "A page of events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "events" ] } }, "/events/{id}": { "get": { "operationId": "eventsGet", "summary": "Fetch one event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Event" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "events" ] } }, "/webhooks": { "get": { "operationId": "webhooksList", "summary": "List webhooks", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "A page of webhooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] }, "post": { "operationId": "webhooksCreate", "summary": "Create a webhook", "description": "The signing secret is returned once, here, and never again. Every delivery is signed with it as HMAC-SHA256.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "identity_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "event_types": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "enum": [ "message.received", "message.sent", "message.delivered", "message.bounced", "message.rejected", "message.complained", "message.spam", "message.invitation", "message.archived", "message.deleted", "calendar.event.created", "calendar.event.updated", "calendar.event.deleted", "calendar.event.starting", "calendar.event.ending", "calendar.event.responded", "thread.created", "thread.updated", "thread.assigned", "thread.unassigned", "identity.created", "identity.updated", "identity.suspended", "identity.transferred", "domain.verified" ] } } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The webhook, and its secret.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookCreated" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] } }, "/webhooks/{id}": { "get": { "operationId": "webhooksGet", "summary": "Fetch one endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] }, "patch": { "operationId": "webhooksUpdate", "summary": "Turn an endpoint off, or back on", "description": "We disable one ourselves after enough consecutive failures. Without this you would have to delete and recreate it, which changes the signing secret every receiver is verifying against. Re-enabling forgives the failure count.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] }, "delete": { "operationId": "webhooksDelete", "summary": "Delete a webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] } }, "/webhooks/{id}/headers": { "get": { "operationId": "webhooksGetHeaders", "summary": "The headers this endpoint carries", "description": "Returned in full. Our signing secret never is, and the difference is whose credential it is: the secret is ours, and these are your own token for your own endpoint.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The headers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookHeaders" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] }, "put": { "operationId": "webhooksUpdateHeaders", "summary": "Replace the headers this endpoint carries", "description": "We sign every delivery, and a signature answers *is this from Pidgeon*. It does not answer the question a gateway asks, which is *does this request carry the token we issued*. PUT, not PATCH: what you send is what the endpoint has afterwards, and `{}` clears them — a merge could not remove one, and removing one is what rotating a token is. The headers we set ourselves are refused by name.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "headers": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } } } } } }, "responses": { "200": { "description": "The headers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookHeaders" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] } }, "/deliveries": { "get": { "operationId": "webhooksDeliveries", "summary": "What happened to each event we tried to hand you", "description": "`webhook_id` is required — the question is always about one endpoint. The ids here are what the replay below takes.", "parameters": [ { "name": "webhook_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "A page of attempts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] } }, "/deliveries/{id}/replay": { "post": { "operationId": "webhooksReplay", "summary": "Send it again", "description": "Re-queues one attempt and resets its count. A verb rather than a status field, because the other statuses are ours to write and mean nothing coming from outside.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Replayed" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "webhooks" ] } }, "/messages/{id}/invitation/respond": { "post": { "operationId": "messagesRespondToInvitation", "summary": "Accept, decline or tentatively accept a meeting", "description": "The one call here that changes something in somebody else's calendar: an iCalendar `REPLY` goes to the organiser, which is how Google, Outlook and Calendly learn about an acceptance. The message must be carrying an `invitation`, and one of this mailbox's own addresses must be on it — including an address routed to it, which is the half you cannot work out from the message. Idempotent on the answer: the same answer to the same `sequence` sends once and returns `already_sent`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted", "declined", "tentative" ] }, "comment": { "type": "string", "maxLength": 4096 } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Already answered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvitationResponse" } }, "required": [ "data" ] } } } }, "202": { "description": "Sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvitationResponse" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "messages" ] } }, "/identities/{id}/calendar": { "get": { "operationId": "calendarGet", "summary": "A mailbox’s calendar", "description": "Every mailbox has exactly one, from the moment it exists, so there is nothing to create. `created_at` is the mailbox’s, because the calendar is the mailbox.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The calendar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Calendar" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] }, "patch": { "operationId": "calendarUpdate", "summary": "Set the default time zone", "description": "The zone an event created without one gets. **Changing it does not move existing events**: an event stores the wall time it was given, so \"every Tuesday at 09:00\" is still 09:00 afterwards.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The `etag` you last read. A stale one is a `409` naming the current version — two agents on one mailbox is the case this product is for, and last-write-wins loses a meeting." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "timezone" ] } } } }, "responses": { "200": { "description": "The calendar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Calendar" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] } }, "/identities/{id}/calendar/events": { "get": { "operationId": "calendarListEvents", "summary": "Everything on the calendar", "description": "Ordered by when it last changed. `GET /agenda` is the other read and the one you usually want: this answers *what is on this calendar*, that answers *what is on between these two moments*.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "The events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] }, "post": { "operationId": "calendarCreateEvent", "summary": "Put something on the calendar", "description": "`start` and `end` are **local wall times with no zone on them** — `2026-10-20T14:00:00` — and `timezone` is a field of its own. That pair is the truth; `starts_at` is the same moment as an instant, derived from it, and it is what survives a daylight-saving change. For an all-day event, `end` is the last day, inclusive.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 1000 }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "all_day": { "default": false, "type": "boolean" }, "description": { "anyOf": [ { "type": "string", "maxLength": 100000 }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "status": { "default": "confirmed", "type": "string", "enum": [ "confirmed", "tentative", "cancelled" ] }, "metadata": {}, "attendees": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ] }, "status": { "default": "needs_action", "type": "string", "enum": [ "needs_action", "accepted", "declined", "tentative" ] }, "optional": { "default": false, "type": "boolean" } }, "required": [ "email" ] } }, "send_invites": { "default": false, "type": "boolean" }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "rule": { "type": "string", "minLength": 1, "maxLength": 600 }, "exdates": { "maxItems": 500, "type": "array", "items": { "type": "string" } }, "rdates": { "maxItems": 500, "type": "array", "items": { "type": "string" } } }, "required": [ "rule" ] }, { "type": "null" } ] } }, "required": [ "title", "start", "end" ] } } } }, "responses": { "201": { "description": "The event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalendarEvent" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] } }, "/identities/{id}/calendar/events/{eventId}/respond": { "post": { "operationId": "calendarRespondToEvent", "summary": "Answer a meeting from the calendar", "description": "The same act as `POST /messages/{id}/invitation/respond`, reached from the other end — an agent working from an agenda holds an event id and not a message id. When the meeting came from mail and `send_reply` is true (the default), an iCalendar `REPLY` goes to the organiser and the answer is written onto the event. When it did not — a meeting this mailbox created itself — there is nobody to reply to, so the answer is recorded and `reply_sent` is false. One of this mailbox’s own addresses must be on the attendee list, including an address routed to it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The `etag` you last read. A stale one is a `409` naming the current version — two agents on one mailbox is the case this product is for, and last-write-wins loses a meeting." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted", "declined", "tentative" ] }, "comment": { "type": "string", "maxLength": 4096 }, "send_reply": { "default": true, "type": "boolean" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Answered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EventResponse" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] } }, "/identities/{id}/calendar/events/{eventId}/instances": { "get": { "operationId": "calendarListEventInstances", "summary": "The dates a series actually happens", "description": "Most of them have no row — they are expanded from the rule, which is what makes a weekly meeting cheap to store. An id here is `{seriesId}::{originalStart}`, derived rather than allocated, and it does **not** change when you edit that date. A date somebody edited comes back in place of the one the rule generated, under that id.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "The dates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] } }, "/identities/{id}/calendar/agenda": { "get": { "operationId": "calendarGetAgenda", "summary": "What is on, in a window, in order", "description": "`include_overlapping` defaults to true, which is the difference between *what starts today* and *what is on today*: a meeting that began last night and runs into this morning is on today, and a naive `starts_at between` misses it. Cancelled events are left out — an agenda is what you are doing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "include_overlapping", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "The agenda.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] } }, "/identities/{id}/calendar/events/{eventId}": { "get": { "operationId": "calendarGetEvent", "summary": "One event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalendarEvent" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] }, "patch": { "operationId": "calendarUpdateEvent", "summary": "Change an event", "description": "An omitted field survives. `sequence` rises only when the change is one attendees see — the time, the title, the place, the status, the list. A `metadata` edit moves the `etag` and not the sequence, because nobody is ever told about it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "single", "future" ] }, "description": "Which dates of a series this is about. Name one **date** of a series — the id `listEventInstances` gives you — and say whether you mean that date (`single`, the default) or that date onwards (`future`, which splits the series). Naming the series means the whole thing, which is why there is no `all`." }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The `etag` you last read. A stale one is a `409` naming the current version — two agents on one mailbox is the case this product is for, and last-write-wins loses a meeting." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 1000 }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "all_day": { "type": "boolean" }, "description": { "anyOf": [ { "type": "string", "maxLength": 100000 }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "confirmed", "tentative", "cancelled" ] }, "metadata": {}, "attendees": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ] }, "status": { "default": "needs_action", "type": "string", "enum": [ "needs_action", "accepted", "declined", "tentative" ] }, "optional": { "default": false, "type": "boolean" } }, "required": [ "email" ] } }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "rule": { "type": "string", "minLength": 1, "maxLength": 600 }, "exdates": { "maxItems": 500, "type": "array", "items": { "type": "string" } }, "rdates": { "maxItems": 500, "type": "array", "items": { "type": "string" } } }, "required": [ "rule" ] }, { "type": "null" } ] }, "send_invites": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalendarEvent" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] }, "delete": { "operationId": "calendarDeleteEvent", "summary": "Take it off the calendar", "description": "On one date of a series this records that the date does not happen rather than removing a row — the rule still generates it, so a removal would bring it straight back. `mode=future` ends the series there and leaves every earlier date alone.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "single", "future" ] }, "description": "Which dates of a series this is about. Name one **date** of a series — the id `listEventInstances` gives you — and say whether you mean that date (`single`, the default) or that date onwards (`future`, which splits the series). Naming the series means the whole thing, which is why there is no `all`." }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The `etag` you last read. A stale one is a `409` naming the current version — two agents on one mailbox is the case this product is for, and last-write-wins loses a meeting." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "calendar" ] } }, "/drafts": { "get": { "operationId": "draftsList", "summary": "Every draft in one mailbox", "description": "Newest first, and including scheduled ones — a scheduled message is a draft with `send_at` set. `GET /mailboxes/drafts` lists the same rows as a mail client draws them: sender, subject, preview. This gives the recipients and the body, because a caller here is coming back to finish writing.", "parameters": [ { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "The drafts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Draft" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to continue. Null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] }, "post": { "operationId": "draftsCreate", "summary": "Write one without sending it", "description": "An agent that drafts a reply, waits for a human to approve it and sends it an hour later is ordinary supervised automation, and this is where the half-written message lives in the meantime. Idempotent with `Idempotency-Key`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identity_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "from": { "type": "string" }, "to": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "cc": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "bcc": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "subject": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "text": { "anyOf": [ { "type": "string", "maxLength": 500000 }, { "type": "null" } ] }, "in_reply_to_message_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "attachment_ids": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "identity_id" ] } } } }, "responses": { "201": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] } }, "/drafts/{id}": { "get": { "operationId": "draftsGet", "summary": "Fetch one draft", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] }, "patch": { "operationId": "draftsUpdate", "summary": "Change some of it, and leave the rest", "description": "An omitted field survives; `null` clears it. Both are needed, because \"I am not touching the subject\" and \"there is no subject\" are different instructions.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "cc": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "bcc": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "subject": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "text": { "anyOf": [ { "type": "string", "maxLength": 500000 }, { "type": "null" } ] }, "attachment_ids": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } } }, "responses": { "200": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] }, "delete": { "operationId": "draftsDelete", "summary": "Throw it away", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] } }, "/drafts/{id}/send": { "post": { "operationId": "draftsSend", "summary": "Send what is stored", "description": "No body: the row is the message. The browser passes the composer contents and the draft id together, because the composer *is* the draft; a caller here saved it an hour ago and may be a different process. `PATCH` first to change anything. The id that comes back is the draft's, because a send converts the row.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Sent" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] } }, "/drafts/{id}/schedule": { "post": { "operationId": "draftsSchedule", "summary": "Send it later", "description": "A minute from now at the earliest, thirty days at the latest. A refused send unschedules rather than retrying forever, so a draft can come back on its own with `failed_reason` set — read that before scheduling the same message again.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "send_at" ] } } } }, "responses": { "200": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] }, "delete": { "operationId": "draftsCancelSchedule", "summary": "Back to being an ordinary draft", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] } }, "/drafts/{id}/attachments/{attachmentId}": { "delete": { "operationId": "draftsRemoveAttachment", "summary": "Take a file off a draft", "description": "The object goes with the row. An attachment belongs to its draft rather than being shared, so leaving the bytes behind would be storage nobody can reach and everybody is billed for. `POST /attachments` is how one gets on.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "drafts" ] } }, "/metrics": { "get": { "operationId": "metricsQuery", "summary": "What happened to the mail", "description": "Counted from the event log rather than from the messages: a message row says what was sent, and whether it bounced is something the provider told us afterwards. `identity_id` narrows it to one mailbox, which is the question worth asking when you run several — reputation belongs to the address that sent the mail. `delivery_rate` is null rather than zero when nothing was sent.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90 } }, { "name": "identity_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Metrics" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "metrics" ] } }, "/attachments": { "post": { "operationId": "attachmentsUpload", "summary": "Upload a file to send", "description": "Multipart, with `identity_id` and `file` parts — not base64 in JSON, because a ten-megabyte PDF is thirteen megabytes of base64 and every proxy in between would have to be told. Name the returned id in `attachment_ids` on a send. An upload expires in a day: it is a file no message refers to yet.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "identity_id", "file" ], "properties": { "identity_id": { "type": "string" }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "The upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UploadedAttachment" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "attachments" ] } }, "/attachments/{id}": { "get": { "operationId": "attachmentsDownloadUrl", "summary": "Get a download link for an attachment", "description": "A signed URL rather than the bytes: streaming a 25 MB file through the API costs the transfer twice and gains the caller nothing. The link expires.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The link.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AttachmentUrl" } }, "required": [ "data" ] } } } }, "401": { "description": "No API key, or one that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. `X-RateLimit-Reset` says when to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "attachments" ] } } }, "tags": [ { "name": "agent" }, { "name": "identities" }, { "name": "labels" }, { "name": "threads" }, { "name": "messages" }, { "name": "domains" }, { "name": "routing" }, { "name": "mailboxes" }, { "name": "keys" }, { "name": "appPasswords" }, { "name": "workspace" }, { "name": "events" }, { "name": "webhooks" }, { "name": "calendar" }, { "name": "drafts" }, { "name": "metrics" }, { "name": "attachments" } ] }