{ "openapi": "3.1.0", "info": { "title": "API Reference", "version": "1.0.0" }, "paths": { "/v0/agent/sign-up": { "post": { "operationId": "agent_signUp", "summary": "Sign Up", "description": "Create a new agent organization with an inbox and API key. This endpoint is for signing up for the first time. If you've already signed up, you're all set — just use your existing API key.\n\nA 6-digit OTP is sent to the human's email for verification.\n\nThis endpoint is idempotent. Calling it again with the same `human_email` will rotate the API key and resend the OTP if expired.\n\nThe returned API key has limited permissions until the organization is verified via the verify endpoint.\n\n**CLI:**\n```bash\nagentmail agent sign-up --human-email user@example.com --username my-agent\n```", "tags": [ "agent" ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_agent:AgentSignupResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_agent:AgentSignupRequest" } } } } } }, "/v0/agent/verify": { "post": { "operationId": "agent_verify", "summary": "Verify", "description": "Verify an agent organization using the 6-digit OTP sent to the human's email during sign-up.\n\nOn success, the organization is upgraded from `agent_unverified` to `agent_verified`, the send allowlist is removed, and free plan entitlements are applied.\n\nThe OTP expires after 24 hours and allows a maximum of 10 attempts. If you run into any difficulties receiving the OTP code, you can also create an account on [console.agentmail.to](https://console.agentmail.to) using the human email address you provided to verify your account.\n\n**CLI:**\n```bash\nagentmail agent verify --otp-code 123456\n```", "tags": [ "agent" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_agent:AgentVerifyResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_agent:AgentVerifyRequest" } } } } } }, "/v0/inboxes": { "get": { "operationId": "inboxes_list", "summary": "List Inboxes", "description": "**CLI:**\n```bash\nagentmail inboxes list\n```", "tags": [ "inboxes" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:ListInboxesResponse" } } } } } }, "post": { "operationId": "inboxes_create", "summary": "Create Inbox", "description": "**CLI:**\n```bash\nagentmail inboxes create --display-name \"My Agent\" --username myagent --domain agentmail.to\n```", "tags": [ "inboxes" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:Inbox" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "422": { "description": "Error response with status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:CreateInboxRequest" } } } } } }, "/v0/inboxes/search": { "get": { "operationId": "inboxes_search", "summary": "Search Inboxes", "description": "Searches inboxes in the organization by address or display name, ranked\nby relevance. Each word in the query matches the start of a word in the\naddress or display name, so `sup` matches `support@example.com` but\n`port` does not. An exact address match always ranks first. `limit`\ncannot exceed 100. A page can be empty and still carry a\n`next_page_token`; keep paging until the token is absent.", "tags": [ "inboxes" ], "parameters": [ { "name": "q", "in": "query", "description": "Address or display name to search for. Matches word prefixes. Must be 2 to 256 characters.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:SearchInboxesResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}": { "get": { "operationId": "inboxes_get", "summary": "Get Inbox", "description": "**CLI:**\n```bash\nagentmail inboxes get --inbox-id \n```", "tags": [ "inboxes" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:Inbox" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "inboxes_update", "summary": "Update Inbox", "description": "**CLI:**\n```bash\nagentmail inboxes update --inbox-id --display-name \"Updated Name\"\n```", "tags": [ "inboxes" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:Inbox" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "description": "Expects an object; provide at least one of `display_name` or `metadata`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:UpdateInboxRequest" } } } } }, "delete": { "operationId": "inboxes_delete", "summary": "Delete Inbox", "description": "**CLI:**\n```bash\nagentmail inboxes delete --inbox-id \n```", "tags": [ "inboxes" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/threads": { "get": { "operationId": "inboxes_threads_list", "summary": "List Threads", "description": "Lists threads in the inbox, most recent first. Pass `senders`,\n`recipients`, or `subject` to filter by substring. Filtered requests are\nserved by search, which caps `limit` at 100. For relevance-ranked\nfull-text search, use `Search Threads`.\n\n**CLI:**\n```bash\nagentmail inboxes threads list --inbox-id \n```", "tags": [ "inboxes > threads" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "labels", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Labels" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "include_spam", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeSpam" } }, { "name": "include_blocked", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeBlocked" } }, { "name": "include_unauthenticated", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeUnauthenticated" } }, { "name": "include_trash", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeTrash" } }, { "name": "senders", "in": "query", "description": "Filter to threads whose senders contain this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "recipients", "in": "query", "description": "Filter to threads whose recipients contain this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "subject", "in": "query", "description": "Filter to threads whose subject contains this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:ListThreadsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/threads/search": { "get": { "operationId": "inboxes_threads_search", "summary": "Search Threads", "description": "Full-text search across threads in the inbox, ranked by relevance. The\nquery is matched against senders, recipients, and subject (substring)\nand the message body (tokenized full text). Spam, trash, blocked, and\nunauthenticated threads are always excluded. `limit` cannot exceed 100.", "tags": [ "inboxes > threads" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "q", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/type_:Query" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:SearchThreadsResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/threads/{thread_id}": { "get": { "operationId": "inboxes_threads_get", "summary": "Get Thread", "description": "**CLI:**\n```bash\nagentmail inboxes threads get --inbox-id --thread-id \n```", "tags": [ "inboxes > threads" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:Thread" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "inboxes_threads_update", "summary": "Update Thread", "description": "Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages.", "tags": [ "inboxes > threads" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:UpdateThreadResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "422": { "description": "Error response with status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:UpdateThreadRequest" } } } } }, "delete": { "operationId": "inboxes_threads_delete", "summary": "Delete Thread", "description": "Permanently deletes a thread and all of its messages.\n\n**CLI:**\n```bash\nagentmail inboxes threads delete --inbox-id --thread-id \n```", "tags": [ "inboxes > threads" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}": { "get": { "operationId": "inboxes_threads_getAttachment", "summary": "Get Attachment", "description": "**CLI:**\n```bash\nagentmail inboxes threads get-attachment --inbox-id --thread-id --attachment-id \n```", "tags": [ "inboxes > threads" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/messages": { "get": { "operationId": "inboxes_messages_list", "summary": "List Messages", "description": "Lists messages in the inbox, most recent first. Pass `from`, `to`, or\n`subject` to filter by substring. Filtered requests are served by\nsearch, which caps `limit` at 100. For relevance-ranked full-text\nsearch across sender, recipients, subject, and message body, use\n`Search Messages`.\n\n**CLI:**\n```bash\nagentmail inboxes messages list --inbox-id \n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "labels", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Labels" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "include_spam", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeSpam" } }, { "name": "include_blocked", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeBlocked" } }, { "name": "include_unauthenticated", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeUnauthenticated" } }, { "name": "include_trash", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeTrash" } }, { "name": "from", "in": "query", "description": "Filter to messages whose sender contains this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "to", "in": "query", "description": "Filter to messages whose recipients (to, cc, or bcc) contain this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "subject", "in": "query", "description": "Filter to messages whose subject contains this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:ListMessagesResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/messages/search": { "get": { "operationId": "inboxes_messages_search", "summary": "Search Messages", "description": "Full-text search across messages in the inbox, ranked by relevance. The\nquery is matched against the sender, recipients, and subject (substring)\nand the message body (tokenized full text). Spam, trash, blocked, and\nunauthenticated messages are always excluded. `limit` cannot exceed 100.", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "q", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/type_:Query" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:SearchMessagesResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/messages/{message_id}": { "get": { "operationId": "inboxes_messages_get", "summary": "Get Message", "description": "**CLI:**\n```bash\nagentmail inboxes messages get --inbox-id --message-id \n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_messages:MessageId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:Message" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "inboxes_messages_update", "summary": "Update Message", "description": "**CLI:**\n```bash\nagentmail inboxes messages update --inbox-id --message-id --add-labels read --remove-labels unread\n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_messages:MessageId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:UpdateMessageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:UpdateMessageRequest" } } } } }, "delete": { "operationId": "inboxes_messages_delete", "summary": "Delete Message", "description": "Permanently deletes a message.\n\n**CLI:**\n```bash\nagentmail inboxes messages delete --inbox-id --message-id \n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_messages:MessageId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/messages/batch-get": { "post": { "operationId": "inboxes_messages_batchGet", "summary": "Batch Get Messages", "description": "Fetch metadata for up to 500 messages in one request. Missing or\nrestricted IDs are silently omitted; compare `count` against `limit`\nto detect misses.\n\n**CLI:**\n```bash\nagentmail inboxes messages batch-get --inbox-id --message-ids --message-ids \n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:BatchGetMessagesResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:BatchGetMessagesRequest" } } } } } }, "/v0/inboxes/{inbox_id}/messages/batch-update": { "post": { "operationId": "inboxes_messages_batchUpdate", "summary": "Batch Update Messages", "description": "Apply one label change to up to 50 messages in a single request. The\nsame add_labels and remove_labels apply to every message id, and at\nleast one of them must be provided. The update is atomic: either all\nresolved messages are updated or none are. Missing or restricted ids\nare silently excluded; compare `count` against `limit` to detect\nexclusions.\n\n**CLI:**\n```bash\nagentmail inboxes messages batch-update --inbox-id --message-ids --message-ids --add-labels read --remove-labels unread\n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:BatchUpdateMessagesResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:BatchUpdateMessagesRequest" } } } } } }, "/v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}": { "get": { "operationId": "inboxes_messages_getAttachment", "summary": "Get Attachment", "description": "**CLI:**\n```bash\nagentmail inboxes messages get-attachment --inbox-id --message-id --attachment-id \n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_messages:MessageId" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/messages/{message_id}/raw": { "get": { "operationId": "inboxes_messages_getRaw", "summary": "Get Raw Message", "description": "**CLI:**\n```bash\nagentmail inboxes messages get-raw --inbox-id --message-id \n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_messages:MessageId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:RawMessageResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/messages/send": { "post": { "operationId": "inboxes_messages_send", "summary": "Send Message", "description": "**CLI:**\n```bash\nagentmail inboxes messages send --inbox-id --to recipient@example.com --subject \"Hello\" --text \"Body\"\n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:SendMessageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "403": { "description": "Error response with status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:SendMessageRequest" } } } } } }, "/v0/inboxes/{inbox_id}/messages/{message_id}/reply": { "post": { "operationId": "inboxes_messages_reply", "summary": "Reply To Message", "description": "**CLI:**\n```bash\nagentmail inboxes messages reply --inbox-id --message-id --text \"Reply text\"\n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_messages:MessageId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:SendMessageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "403": { "description": "Error response with status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:ReplyToMessageRequest" } } } } } }, "/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all": { "post": { "operationId": "inboxes_messages_reply-all", "summary": "Reply All Message", "description": "**CLI:**\n```bash\nagentmail inboxes messages reply-all --inbox-id --message-id --text \"Reply text\"\n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_messages:MessageId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:SendMessageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "403": { "description": "Error response with status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:ReplyAllMessageRequest" } } } } } }, "/v0/inboxes/{inbox_id}/messages/{message_id}/forward": { "post": { "operationId": "inboxes_messages_forward", "summary": "Forward Message", "description": "**CLI:**\n```bash\nagentmail inboxes messages forward --inbox-id --message-id --to recipient@example.com\n```", "tags": [ "inboxes > messages" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_messages:MessageId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:SendMessageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "403": { "description": "Error response with status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:SendMessageRequest" } } } } } }, "/v0/inboxes/{inbox_id}/drafts": { "get": { "operationId": "inboxes_drafts_list", "summary": "List Drafts", "description": "**CLI:**\n```bash\nagentmail inboxes drafts list --inbox-id \n```", "tags": [ "inboxes > drafts" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "labels", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Labels" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:ListDraftsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "post": { "operationId": "inboxes_drafts_create", "summary": "Create Draft", "description": "Create a draft. Supply `in_reply_to` to create a reply draft (with\n`reply_all` to address the whole thread), whose recipients, subject, and\nthreading are derived from the referenced message, or `forward_of` to\ncreate a forward draft, which derives the subject, threading, and\nforwarded content from the source but keeps recipients caller-supplied.\n\n**CLI:**\n```bash\nagentmail inboxes drafts create --inbox-id --to recipient@example.com --subject \"Draft subject\" --text \"Draft body\"\n```", "tags": [ "inboxes > drafts" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:Draft" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:CreateDraftRequest" } } } } } }, "/v0/inboxes/{inbox_id}/drafts/{draft_id}": { "get": { "operationId": "inboxes_drafts_get", "summary": "Get Draft", "description": "**CLI:**\n```bash\nagentmail inboxes drafts get --inbox-id --draft-id \n```", "tags": [ "inboxes > drafts" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:Draft" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "inboxes_drafts_update", "summary": "Update Draft", "description": "Edit fields on an existing draft. Passing `null` clears a field (or `[]`\nfor a recipient field); `send_at: null` un-schedules a scheduled draft.\nA draft that is already being sent cannot be edited.\n\n**CLI:**\n```bash\nagentmail inboxes drafts update --inbox-id --draft-id --subject \"Updated subject\"\n```", "tags": [ "inboxes > drafts" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:Draft" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:UpdateDraftRequest" } } } } }, "delete": { "operationId": "inboxes_drafts_delete", "summary": "Delete Draft", "description": "**CLI:**\n```bash\nagentmail inboxes drafts delete --inbox-id --draft-id \n```", "tags": [ "inboxes > drafts" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}": { "get": { "operationId": "inboxes_drafts_getAttachment", "summary": "Get Attachment", "description": "**CLI:**\n```bash\nagentmail inboxes drafts get-attachment --inbox-id --draft-id --attachment-id \n```", "tags": [ "inboxes > drafts" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/drafts/{draft_id}/send": { "post": { "operationId": "inboxes_drafts_send", "summary": "Send Draft", "description": "**CLI:**\n```bash\nagentmail inboxes drafts send --inbox-id --draft-id \n```", "tags": [ "inboxes > drafts" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:SendMessageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "403": { "description": "Error response with status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_messages:UpdateMessageRequest" } } } } } }, "/v0/inboxes/{inbox_id}/browser-credentials/enrollments": { "post": { "operationId": "inboxes_browserCredentials_createEnrollment", "summary": "Create Browser Enrollment", "description": "Attach a browser enrollment intent to the inbox. Requires\n`api_key_create`. Before submitting `transaction_jti`, independently\nverify that the browser page's final origin is exactly\n`https://auth.agentid.com`.\n\nThis endpoint is available to every organization using US production.\nIt is not available in EU production.\n\nSelect `inbox_id` from trusted AgentMail configuration. An AgentID\n`login_hint` is not authoritative for selecting the inbox; when the\ntransaction includes one, it must match the path inbox.\n\n**AgentMail API keys are sent only to `https://api.agentmail.to`; AgentID never requests them.**\n\nA new intent returns `202`; an idempotent retry for the same pending\ntransaction, inbox, and bearer key returns `200` with the same receipt.\nAn intent lasts at most five minutes. An activated credential lasts at\nmost 30 days and cannot outlive its authorizing bearer API key.\n\nCreation is limited to 20 intents per bearer API key per hour, 100 per\norganization per hour, and five live unused intents per bearer API key.\nBrowser activation is separately limited to 20 activations per\nauthorizing bearer API key per UTC day. Either kind of limit can return\n`429`; honor the `Retry-After` header. Cancelling an enrollment releases\nits live-intent slot but does not reset the daily activation counter.", "tags": [ "inboxes > browser-credentials" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Response with status 202", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:BrowserEnrollmentAccepted" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:CreateBrowserEnrollmentRequest" } } } } } }, "/v0/inboxes/{inbox_id}/webhooks": { "get": { "operationId": "inboxes_webhooks_list", "summary": "List Webhooks", "description": "**CLI:**\n```bash\nagentmail inboxes webhooks list --inbox-id \n```", "tags": [ "inboxes > webhooks" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:ListWebhooksResponse" } } } } } }, "post": { "operationId": "inboxes_webhooks_create", "summary": "Create Webhook", "description": "Create a webhook scoped to this inbox.\n\n**CLI:**\n```bash\nagentmail inboxes webhooks create --inbox-id --url https://example.com/webhook --event-types message.received\n```", "tags": [ "inboxes > webhooks" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:CreateInboxWebhookRequest" } } } } } }, "/v0/inboxes/{inbox_id}/webhooks/{webhook_id}": { "get": { "operationId": "inboxes_webhooks_get", "summary": "Get Webhook", "description": "**CLI:**\n```bash\nagentmail inboxes webhooks get --inbox-id --webhook-id \n```", "tags": [ "inboxes > webhooks" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "inboxes_webhooks_update", "summary": "Update Webhook", "description": "**CLI:**\n```bash\nagentmail inboxes webhooks update --inbox-id --webhook-id --event-types message.received\n```", "tags": [ "inboxes > webhooks" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:UpdateInboxWebhookRequest" } } } } }, "delete": { "operationId": "inboxes_webhooks_delete", "summary": "Delete Webhook", "description": "**CLI:**\n```bash\nagentmail inboxes webhooks delete --inbox-id --webhook-id \n```", "tags": [ "inboxes > webhooks" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers": { "get": { "operationId": "inboxes_webhooks_getHeaders", "summary": "Get Webhook Headers", "description": "List the names of custom HTTP headers included with deliveries to this inbox-scoped webhook.\nHeader values are write-only and are never returned.", "tags": [ "inboxes > webhooks" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookHeaderNamesResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "inboxes_webhooks_updateHeaders", "summary": "Update Webhook Headers", "description": "Atomically set, replace, or remove custom HTTP headers included with deliveries to this\ninbox-scoped webhook. Header values remain write-only.", "tags": [ "inboxes > webhooks" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Response with status 204", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:UpdateWebhookHeadersRequest" } } } } } }, "/v0/inboxes/{inbox_id}/lists/{direction}/{type}": { "get": { "operationId": "inboxes_lists_list", "summary": "List Entries", "description": "**CLI:**\n```bash\nagentmail inboxes lists list --inbox-id --direction --type \n```", "tags": [ "inboxes > lists" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:PodListListEntriesResponse" } } } } } }, "post": { "operationId": "inboxes_lists_create", "summary": "Create List Entry", "description": "**CLI:**\n```bash\nagentmail inboxes lists create --inbox-id --direction --type --entry user@example.com\n```", "tags": [ "inboxes > lists" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:PodListEntry" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:CreateListEntryRequest" } } } } } }, "/v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}": { "get": { "operationId": "inboxes_lists_get", "summary": "Get List Entry", "description": "**CLI:**\n```bash\nagentmail inboxes lists get --inbox-id --direction --type --entry \n```", "tags": [ "inboxes > lists" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "entry", "in": "path", "description": "Email address or domain.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:PodListEntry" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "delete": { "operationId": "inboxes_lists_delete", "summary": "Delete List Entry", "description": "**CLI:**\n```bash\nagentmail inboxes lists delete --inbox-id --direction --type --entry \n```", "tags": [ "inboxes > lists" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "entry", "in": "path", "description": "Email address or domain.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/metrics/events": { "get": { "operationId": "inboxes_metrics_queryEvents", "summary": "Query Events", "description": "Counts of email events (sent, delivered, bounced, etc.) over time for\nthe inbox. Defaults to the last 24 hours; `start` must be within the\nlast 90 days, and a future `end` is clamped to now. Omit `period` for\nindividual event counts, or set it to sum counts into buckets of that\nmany seconds.\n\n**CLI:**\n```bash\nagentmail inboxes metrics query-events --inbox-id \n```", "tags": [ "inboxes > metrics" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "event_types", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricEventTypes" } }, { "name": "start", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Start" } }, { "name": "end", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:End" } }, { "name": "period", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Period" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricLimit" } }, { "name": "descending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Descending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_metrics:QueryMetricsResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/metrics/usage": { "get": { "operationId": "inboxes_metrics_queryUsage", "summary": "Query Usage", "description": "Cumulative usage series for the inbox. Each point is the running total\nof the usage type at that timestamp, not the change within the bucket.\nInbox-scoped queries carry `storage_bytes`, `message_count`, and\n`thread_count`; requested types that don't apply to the scope are\nignored. Defaults to the last 24 hours; `start` must be within the\nlast 90 days, and a future `end` is clamped to now. The range divided\nby `period` must not exceed 1000 buckets.", "tags": [ "inboxes > metrics" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "usage_types", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:UsageTypes" } }, { "name": "start", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Start" } }, { "name": "end", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:End" } }, { "name": "period", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Period" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricLimit" } }, { "name": "descending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Descending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_metrics:QueryUsageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/events": { "get": { "operationId": "inboxes_events_list", "summary": "List Inbox Events", "description": "List label change events for an inbox. Returns events in reverse chronological order by default. Use for IMAP UID projection or audit logging.\n\n**CLI:**\n```bash\nagentmail inboxes events list --inbox-id \n```", "tags": [ "inboxes > events" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inbox-events:ListInboxEventsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/inboxes/{inbox_id}/api-keys": { "get": { "operationId": "inboxes_apiKeys_list", "summary": "List API Keys", "description": "**CLI:**\n```bash\nagentmail inboxes api-keys list --inbox-id \n```", "tags": [ "inboxes > api-keys" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:ListApiKeysResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "post": { "operationId": "inboxes_apiKeys_create", "summary": "Create API Key", "description": "**CLI:**\n```bash\nagentmail inboxes api-keys create --inbox-id --name \"My Key\"\n```", "tags": [ "inboxes > api-keys" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:CreateApiKeyResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:CreateApiKeyRequest" } } } } } }, "/v0/inboxes/{inbox_id}/api-keys/{api_key_id}": { "delete": { "operationId": "inboxes_apiKeys_delete", "summary": "Delete API Key", "description": "**CLI:**\n```bash\nagentmail inboxes api-keys delete --inbox-id --api-key-id \n```", "tags": [ "inboxes > api-keys" ], "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "api_key_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_api-keys:ApiKeyId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/threads": { "get": { "operationId": "threads_list", "summary": "List Threads", "description": "Lists threads, most recent first. Pass `senders`, `recipients`, or\n`subject` to filter by substring. Filtered requests are served by\nsearch, which caps `limit` at 100. For relevance-ranked full-text\nsearch across senders, recipients, subject, and message body, use\n`Search Threads`.\n\n**CLI:**\n```bash\nagentmail threads list\n```", "tags": [ "threads" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "labels", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Labels" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "include_spam", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeSpam" } }, { "name": "include_blocked", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeBlocked" } }, { "name": "include_unauthenticated", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeUnauthenticated" } }, { "name": "include_trash", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeTrash" } }, { "name": "senders", "in": "query", "description": "Filter to threads whose senders contain this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "recipients", "in": "query", "description": "Filter to threads whose recipients contain this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "subject", "in": "query", "description": "Filter to threads whose subject contains this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:ListThreadsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/threads/search": { "get": { "operationId": "threads_search", "summary": "Search Threads", "description": "Full-text search across threads in the organization, ranked by\nrelevance. The query is matched against senders, recipients, and\nsubject (substring) and the message body (tokenized full text). Spam,\ntrash, blocked, and unauthenticated threads are always excluded.\n`limit` cannot exceed 100.", "tags": [ "threads" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/type_:Query" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:SearchThreadsResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/threads/{thread_id}": { "get": { "operationId": "threads_get", "summary": "Get Thread", "description": "**CLI:**\n```bash\nagentmail threads get --thread-id \n```", "tags": [ "threads" ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:Thread" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "threads_update", "summary": "Update Thread", "description": "Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages.", "tags": [ "threads" ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:UpdateThreadResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "422": { "description": "Error response with status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:UpdateThreadRequest" } } } } }, "delete": { "operationId": "threads_delete", "summary": "Delete Thread", "description": "Permanently deletes a thread and all of its messages.\n\n**CLI:**\n```bash\nagentmail threads delete --thread-id \n```", "tags": [ "threads" ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/threads/{thread_id}/attachments/{attachment_id}": { "get": { "operationId": "threads_getAttachment", "summary": "Get Attachment", "description": "**CLI:**\n```bash\nagentmail threads get-attachment --thread-id --attachment-id \n```", "tags": [ "threads" ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/drafts": { "get": { "operationId": "drafts_list", "summary": "List Drafts", "description": "**CLI:**\n```bash\nagentmail drafts list\n```", "tags": [ "drafts" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "labels", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Labels" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:ListDraftsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/drafts/{draft_id}": { "get": { "operationId": "drafts_get", "summary": "Get Draft", "description": "**CLI:**\n```bash\nagentmail drafts get --draft-id \n```", "tags": [ "drafts" ], "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:Draft" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/drafts/{draft_id}/attachments/{attachment_id}": { "get": { "operationId": "drafts_getAttachment", "summary": "Get Attachment", "description": "**CLI:**\n```bash\nagentmail drafts get-attachment --draft-id --attachment-id \n```", "tags": [ "drafts" ], "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/webhooks": { "get": { "operationId": "webhooks_list", "summary": "List Webhooks", "description": "**CLI:**\n```bash\nagentmail webhooks list\n```", "tags": [ "webhooks" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:ListWebhooksResponse" } } } } } }, "post": { "operationId": "webhooks_create", "summary": "Create Webhook", "description": "**CLI:**\n```bash\nagentmail webhooks create --url https://example.com/webhook --event-types message.received\n```", "tags": [ "webhooks" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:CreateWebhookRequest" } } } } } }, "/v0/webhooks/{webhook_id}": { "get": { "operationId": "webhooks_get", "summary": "Get Webhook", "description": "**CLI:**\n```bash\nagentmail webhooks get --webhook-id \n```", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "webhooks_update", "summary": "Update Webhook", "description": "Update inbox or pod subscriptions, or replace the webhook's `event_types` in full when you pass a\nnon-empty `event_types` array (see request field docs). Inbox and pod changes use add/remove lists.\n\n**CLI:**\n```bash\nagentmail webhooks update --webhook-id --add-inbox-ids \n```", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:UpdateWebhookRequest" } } } } }, "delete": { "operationId": "webhooks_delete", "summary": "Delete Webhook", "description": "**CLI:**\n```bash\nagentmail webhooks delete --webhook-id \n```", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/webhooks/{webhook_id}/headers": { "get": { "operationId": "webhooks_getHeaders", "summary": "Get Webhook Headers", "description": "List the names of custom HTTP headers included with deliveries to this webhook. Header values are\nwrite-only and are never returned.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookHeaderNamesResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "webhooks_updateHeaders", "summary": "Update Webhook Headers", "description": "Atomically set, replace, or remove custom HTTP headers included with deliveries to this webhook.\nHeader values remain write-only.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Response with status 204", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:UpdateWebhookHeadersRequest" } } } } } }, "/v0/domains": { "get": { "operationId": "domains_list", "summary": "List Domains", "description": "**CLI:**\n```bash\nagentmail domains list\n```", "tags": [ "domains" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:ListDomainsResponse" } } } } } }, "post": { "operationId": "domains_create", "summary": "Create Domain", "description": "**CLI:**\n```bash\nagentmail domains create --domain example.com\n```", "tags": [ "domains" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:Domain" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:CreateDomainRequest" } } } } } }, "/v0/domains/{domain_id}": { "get": { "operationId": "domains_get", "summary": "Get Domain", "description": "**CLI:**\n```bash\nagentmail domains get --domain-id \n```", "tags": [ "domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:Domain" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "domains_update", "summary": "Update Domain", "description": "**CLI:**\n```bash\nagentmail domains update --domain-id \n```", "tags": [ "domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:Domain" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:UpdateDomainRequest" } } } } }, "delete": { "operationId": "domains_delete", "summary": "Delete Domain", "description": "**CLI:**\n```bash\nagentmail domains delete --domain-id \n```", "tags": [ "domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/domains/{domain_id}/zone-file": { "get": { "operationId": "domains_getZoneFile", "summary": "Get Zone File", "description": "**CLI:**\n```bash\nagentmail domains get-zone-file --domain-id \n```", "tags": [ "domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/domains/{domain_id}/verify": { "post": { "operationId": "domains_verify", "summary": "Verify Domain", "description": "**CLI:**\n```bash\nagentmail domains verify --domain-id \n```", "tags": [ "domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "422": { "description": "Error response with status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/domains/{domain_id}/setup-link": { "get": { "operationId": "domains_getSetupLink", "summary": "Get Setup Link", "description": "Build a one-click DNS setup link for the domain via the Domain Connect standard. When the domain's DNS provider supports Domain Connect and carries the AgentMail template, the response contains a signed URL: opening it lets the domain owner approve the required DNS records at their provider, which writes them automatically — no copy-paste. When the provider does not support it, `supported` is `false` and the domain's `records` should be added manually instead.", "tags": [ "domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:GetSetupLinkResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "422": { "description": "Error response with status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/lists/{direction}/{type}": { "get": { "operationId": "lists_list", "summary": "List Entries", "description": "**CLI:**\n```bash\nagentmail lists list --direction --type \n```", "tags": [ "lists" ], "parameters": [ { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:ListListEntriesResponse" } } } } } }, "post": { "operationId": "lists_create", "summary": "Create List Entry", "description": "**CLI:**\n```bash\nagentmail lists create --direction --type --entry user@example.com\n```", "tags": [ "lists" ], "parameters": [ { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:ListEntry" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:CreateListEntryRequest" } } } } } }, "/v0/lists/{direction}/{type}/{entry}": { "get": { "operationId": "lists_get", "summary": "Get List Entry", "description": "**CLI:**\n```bash\nagentmail lists get --direction --type --entry \n```", "tags": [ "lists" ], "parameters": [ { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "entry", "in": "path", "description": "Email address or domain.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:ListEntry" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "delete": { "operationId": "lists_delete", "summary": "Delete List Entry", "description": "**CLI:**\n```bash\nagentmail lists delete --direction --type --entry \n```", "tags": [ "lists" ], "parameters": [ { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "entry", "in": "path", "description": "Email address or domain.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/metrics/events": { "get": { "operationId": "metrics_queryEvents", "summary": "Query Events", "description": "Counts of email events (sent, delivered, bounced, etc.) over time for\nthe organization. Defaults to the last 24 hours; `start` must be within\nthe last 90 days, and a future `end` is clamped to now. Omit `period`\nfor individual event counts, or set it to sum counts into buckets of\nthat many seconds.\n\n**CLI:**\n```bash\nagentmail metrics query-events\n```", "tags": [ "metrics" ], "parameters": [ { "name": "event_types", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricEventTypes" } }, { "name": "start", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Start" } }, { "name": "end", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:End" } }, { "name": "period", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Period" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricLimit" } }, { "name": "descending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Descending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_metrics:QueryMetricsResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/metrics/usage": { "get": { "operationId": "metrics_queryUsage", "summary": "Query Usage", "description": "Cumulative usage series for the organization. Each point is the running\ntotal of the usage type at that timestamp, not the change within the\nbucket. Defaults to the last 24 hours; `start` must be within the last\n90 days, and a future `end` is clamped to now. The range divided by\n`period` must not exceed 1000 buckets.", "tags": [ "metrics" ], "parameters": [ { "name": "usage_types", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:UsageTypes" } }, { "name": "start", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Start" } }, { "name": "end", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:End" } }, { "name": "period", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Period" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricLimit" } }, { "name": "descending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Descending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_metrics:QueryUsageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/api-keys": { "get": { "operationId": "apiKeys_list", "summary": "List API Keys", "description": "**CLI:**\n```bash\nagentmail api-keys list\n```", "tags": [ "api-keys" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:ListApiKeysResponse" } } } } } }, "post": { "operationId": "apiKeys_create", "summary": "Create API Key", "description": "**CLI:**\n```bash\nagentmail api-keys create --name \"My Key\"\n```", "tags": [ "api-keys" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:CreateApiKeyResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:CreateApiKeyRequest" } } } } } }, "/v0/api-keys/{api_key_id}": { "delete": { "operationId": "apiKeys_delete", "summary": "Delete API Key", "description": "**CLI:**\n```bash\nagentmail api-keys delete --api-key-id \n```", "tags": [ "api-keys" ], "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_api-keys:ApiKeyId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/api-keys/public-keys": { "get": { "operationId": "apiKeys_listPublicKeys", "summary": "List Public-Key Credentials", "description": "List only public-key credentials visible to the bearer caller's scope.\nBearer credentials are never returned, even though both credential types\nshare storage and pagination indexes. Requires `api_key_read`.", "tags": [ "api-keys" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:ListPublicKeysResponse" } } } } } }, "post": { "operationId": "apiKeys_createPublicKey", "summary": "Register Public-Key Credential", "description": "Register a public P-256 JWK using an existing AgentMail bearer API key\nwith `api_key_create`. Re-registering the same JWK creates a new\ncredential ID; it does not replace or recover an earlier credential.\nThe private key must never be sent to AgentMail.", "tags": [ "api-keys" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:PublicKeyCredential" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:CreatePublicKeyRequest" } } } } } }, "/v0/api-keys/public-keys/{api_key_id}": { "patch": { "operationId": "apiKeys_updatePublicKeyName", "summary": "Rename Public-Key Credential", "description": "Rename the credential. All security-relevant fields are immutable.\nRequires `api_key_update`.", "tags": [ "api-keys" ], "parameters": [ { "name": "api_key_id", "in": "path", "description": "Public-key credential ID returned by registration.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:PublicKeyCredential" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:UpdatePublicKeyNameRequest" } } } } }, "delete": { "operationId": "apiKeys_revokePublicKey", "summary": "Revoke Public-Key Credential", "description": "Permanently revoke one public-key credential. This hard-deletes the\ncredential; repeating the request returns not found. Requires\n`api_key_delete`.", "tags": [ "api-keys" ], "parameters": [ { "name": "api_key_id", "in": "path", "description": "Public-key credential ID returned by registration.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Response with status 204", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/api-keys/public-keys/agentid-sign-in/revoke-all": { "post": { "operationId": "apiKeys_revokeAllAgentIdSignInKeys", "summary": "Revoke All AgentID Sign-In Keys", "description": "Invalidate every current public-key credential in the caller's\norganization by advancing its AgentID key generation. The caller must be\norganization-scoped and either have `api_key_delete` or, for a verified\nself-serve agent organization, use an unrestricted unmanaged bearer\ncredential. No request body is accepted.\n\n`Idempotency-Key` is required and must be a UUID. Reusing the same UUID\nreturns the original permanent receipt without advancing the generation\nagain. A new UUID performs a new generation advance.", "tags": [ "api-keys" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required UUID identifying this revoke-all operation permanently.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:RevokeAllAgentIdSignInKeysResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/api-keys/browser-credentials": { "get": { "operationId": "apiKeys_listBrowserCredentials", "summary": "List Browser Credentials", "description": "List active browser credentials visible to the caller's scope. Requires `api_key_read`.", "tags": [ "api-keys" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_api-keys:BrowserAuthorizationListLimit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:ListBrowserCredentialsResponse" } } } } } } }, "/v0/api-keys/browser-credentials/events": { "get": { "operationId": "apiKeys_listBrowserCredentialEvents", "summary": "List Browser Credential Events", "description": "List owner-facing browser credential and consent lifecycle events. Requires `api_key_read`.", "tags": [ "api-keys" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_api-keys:BrowserAuthorizationListLimit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:ListBrowserLifecycleEventsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/api-keys/browser-credentials/{credential_id}": { "delete": { "operationId": "apiKeys_deleteBrowserCredential", "summary": "Delete Browser Credential", "description": "Permanently revoke one active browser credential. Requires `api_key_delete`.", "tags": [ "api-keys" ], "parameters": [ { "name": "credential_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Response with status 204", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/api-keys/browser-credentials/enrollments/{enrollment_id}": { "delete": { "operationId": "apiKeys_cancelBrowserEnrollment", "summary": "Cancel Browser Enrollment", "description": "Cancel one pending, unexpired browser enrollment intent. Requires `api_key_delete`.", "tags": [ "api-keys" ], "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Response with status 204", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/api-keys/browser-consents": { "get": { "operationId": "apiKeys_listBrowserConsents", "summary": "List Browser Consents", "description": "List remembered AgentID client approvals for one live inbox. Requires `api_key_read`.", "tags": [ "api-keys" ], "parameters": [ { "name": "inbox_id", "in": "query", "required": true, "schema": { "type": "string", "format": "email", "maxLength": 254 } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_api-keys:BrowserAuthorizationListLimit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:ListBrowserConsentsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/api-keys/browser-consents/{consent_id}": { "delete": { "operationId": "apiKeys_deleteBrowserConsent", "summary": "Delete Browser Consent", "description": "Revoke one remembered AgentID client approval. Requires `api_key_delete`.", "tags": [ "api-keys" ], "parameters": [ { "name": "consent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Response with status 204", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/providers": { "get": { "operationId": "providers_list", "summary": "List Providers", "description": "Lists providers, most popular first.", "tags": [ "providers" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_providers:ListProvidersResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/providers/search": { "get": { "operationId": "providers_search", "summary": "Search Providers", "description": "Searches providers by name prefix.", "tags": [ "providers" ], "parameters": [ { "name": "q", "in": "query", "description": "Name prefix to search for.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_providers:SearchProvidersResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/providers/{provider_id}": { "get": { "operationId": "providers_get", "summary": "Get Provider", "tags": [ "providers" ], "parameters": [ { "name": "provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_accounts:ProviderId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_providers:Provider" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/providers/{provider_id}/accounts": { "get": { "operationId": "providers_listAccounts", "summary": "List Provider Accounts", "description": "Lists accounts at one provider, most recent sign-in first.", "tags": [ "providers" ], "parameters": [ { "name": "provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_accounts:ProviderId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_providers:ListProviderAccountsResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/providers/{provider_id}/connect": { "post": { "operationId": "providers_connect", "summary": "Connect Provider", "description": "Starts signing an inbox in to a provider. Returns a `magic_url` valid\nfor five minutes; open it in the browser that will hold the sign-in.\nRequires `api_key_create` and an `Idempotency-Key` header.", "tags": [ "providers" ], "parameters": [ { "name": "provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_accounts:ProviderId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Response with status 202", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_providers:ConnectProviderAccepted" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "409": { "description": "Error response with status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_providers:ConnectProviderBody" } } } } } }, "/v0/accounts": { "get": { "operationId": "accounts_list", "summary": "List Accounts", "description": "Lists accounts across all providers.", "tags": [ "accounts" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_accounts:ListAccountsResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/accounts/{account_id}": { "get": { "operationId": "accounts_get", "summary": "Get Account", "tags": [ "accounts" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_accounts:AccountId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_accounts:Account" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods": { "get": { "operationId": "pods_list", "summary": "List Pods", "description": "**CLI:**\n```bash\nagentmail pods list\n```", "tags": [ "pods" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_pods:ListPodsResponse" } } } } } }, "post": { "operationId": "pods_create", "summary": "Create Pod", "description": "**CLI:**\n```bash\nagentmail pods create --client-id my-pod\n```", "tags": [ "pods" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_pods:Pod" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_pods:CreatePodRequest" } } } } } }, "/v0/pods/{pod_id}": { "get": { "operationId": "pods_get", "summary": "Get Pod", "description": "**CLI:**\n```bash\nagentmail pods get --pod-id \n```", "tags": [ "pods" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_pods:Pod" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "delete": { "operationId": "pods_delete", "summary": "Delete Pod", "description": "**CLI:**\n```bash\nagentmail pods delete --pod-id \n```", "tags": [ "pods" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/inboxes": { "get": { "operationId": "pods_inboxes_list", "summary": "List Inboxes", "description": "**CLI:**\n```bash\nagentmail pods inboxes list --pod-id \n```", "tags": [ "pods > inboxes" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:ListInboxesResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "post": { "operationId": "pods_inboxes_create", "summary": "Create Inbox", "description": "**CLI:**\n```bash\nagentmail pods inboxes create --pod-id --username myagent --domain example.com\n```", "tags": [ "pods > inboxes" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:Inbox" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "422": { "description": "Error response with status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:CreateInboxRequest" } } } } } }, "/v0/pods/{pod_id}/inboxes/search": { "get": { "operationId": "pods_inboxes_search", "summary": "Search Inboxes", "description": "Searches inboxes in the pod by address or display name, ranked by\nrelevance. Each word in the query matches the start of a word in the\naddress or display name, so `sup` matches `support@example.com` but\n`port` does not. An exact address match always ranks first. `limit`\ncannot exceed 100. A page can be empty and still carry a\n`next_page_token`; keep paging until the token is absent.", "tags": [ "pods > inboxes" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "q", "in": "query", "description": "Address or display name to search for. Matches word prefixes. Must be 2 to 256 characters.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:SearchInboxesResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/inboxes/{inbox_id}": { "get": { "operationId": "pods_inboxes_get", "summary": "Get Inbox", "description": "**CLI:**\n```bash\nagentmail pods inboxes get --pod-id --inbox-id \n```", "tags": [ "pods > inboxes" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:Inbox" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "pods_inboxes_update", "summary": "Update Inbox", "description": "**CLI:**\n```bash\nagentmail pods inboxes update --pod-id --inbox-id \n```", "tags": [ "pods > inboxes" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:Inbox" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_inboxes:UpdateInboxRequest" } } } } }, "delete": { "operationId": "pods_inboxes_delete", "summary": "Delete Inbox", "description": "**CLI:**\n```bash\nagentmail pods inboxes delete --pod-id --inbox-id \n```", "tags": [ "pods > inboxes" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "inbox_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_inboxes:InboxId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/threads": { "get": { "operationId": "pods_threads_list", "summary": "List Threads", "description": "Lists threads in the pod, most recent first. Pass `senders`,\n`recipients`, or `subject` to filter by substring. Filtered requests are\nserved by search, which caps `limit` at 100. For relevance-ranked\nfull-text search, use `Search Threads`.\n\n**CLI:**\n```bash\nagentmail pods threads list --pod-id \n```", "tags": [ "pods > threads" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "labels", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Labels" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "include_spam", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeSpam" } }, { "name": "include_blocked", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeBlocked" } }, { "name": "include_unauthenticated", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeUnauthenticated" } }, { "name": "include_trash", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:IncludeTrash" } }, { "name": "senders", "in": "query", "description": "Filter to threads whose senders contain this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "recipients", "in": "query", "description": "Filter to threads whose recipients contain this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "subject", "in": "query", "description": "Filter to threads whose subject contains this value (substring match). Repeatable; all values must match.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:ListThreadsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/threads/search": { "get": { "operationId": "pods_threads_search", "summary": "Search Threads", "description": "Full-text search across threads in the pod, ranked by relevance. The\nquery is matched against senders, recipients, and subject (substring)\nand the message body (tokenized full text). Spam, trash, blocked, and\nunauthenticated threads are always excluded. `limit` cannot exceed 100.", "tags": [ "pods > threads" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "q", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/type_:Query" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:SearchThreadsResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/threads/{thread_id}": { "get": { "operationId": "pods_threads_get", "summary": "Get Thread", "description": "**CLI:**\n```bash\nagentmail pods threads get --pod-id --thread-id \n```", "tags": [ "pods > threads" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:Thread" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "pods_threads_update", "summary": "Update Thread", "description": "Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages.", "tags": [ "pods > threads" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:UpdateThreadResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } }, "422": { "description": "Error response with status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_threads:UpdateThreadRequest" } } } } }, "delete": { "operationId": "pods_threads_delete", "summary": "Delete Thread", "description": "Permanently deletes a thread and all of its messages.\n\n**CLI:**\n```bash\nagentmail pods threads delete --pod-id --thread-id \n```", "tags": [ "pods > threads" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/threads/{thread_id}/attachments/{attachment_id}": { "get": { "operationId": "pods_threads_getAttachment", "summary": "Get Attachment", "description": "**CLI:**\n```bash\nagentmail pods threads get-attachment --pod-id --thread-id --attachment-id \n```", "tags": [ "pods > threads" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/drafts": { "get": { "operationId": "pods_drafts_list", "summary": "List Drafts", "description": "**CLI:**\n```bash\nagentmail pods drafts list --pod-id \n```", "tags": [ "pods > drafts" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "labels", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Labels" } }, { "name": "before", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:After" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:ListDraftsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/drafts/{draft_id}": { "get": { "operationId": "pods_drafts_get", "summary": "Get Draft", "description": "**CLI:**\n```bash\nagentmail pods drafts get --pod-id --draft-id \n```", "tags": [ "pods > drafts" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_drafts:Draft" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/drafts/{draft_id}/attachments/{attachment_id}": { "get": { "operationId": "pods_drafts_getAttachment", "summary": "Get Attachment", "description": "**CLI:**\n```bash\nagentmail pods drafts get-attachment --pod-id --draft-id --attachment-id \n```", "tags": [ "pods > drafts" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_drafts:DraftId" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_attachments:AttachmentResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/webhooks": { "get": { "operationId": "pods_webhooks_list", "summary": "List Webhooks", "description": "**CLI:**\n```bash\nagentmail pods webhooks list --pod-id \n```", "tags": [ "pods > webhooks" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:ListWebhooksResponse" } } } } } }, "post": { "operationId": "pods_webhooks_create", "summary": "Create Webhook", "description": "Create a webhook scoped to this pod.\n\n**CLI:**\n```bash\nagentmail pods webhooks create --pod-id --url https://example.com/webhook --event-types message.received\n```", "tags": [ "pods > webhooks" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:CreatePodWebhookRequest" } } } } } }, "/v0/pods/{pod_id}/webhooks/{webhook_id}": { "get": { "operationId": "pods_webhooks_get", "summary": "Get Webhook", "description": "**CLI:**\n```bash\nagentmail pods webhooks get --pod-id --webhook-id \n```", "tags": [ "pods > webhooks" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "pods_webhooks_update", "summary": "Update Webhook", "description": "**CLI:**\n```bash\nagentmail pods webhooks update --pod-id --webhook-id --add-inbox-ids \n```", "tags": [ "pods > webhooks" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:Webhook" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:UpdatePodWebhookRequest" } } } } }, "delete": { "operationId": "pods_webhooks_delete", "summary": "Delete Webhook", "description": "**CLI:**\n```bash\nagentmail pods webhooks delete --pod-id --webhook-id \n```", "tags": [ "pods > webhooks" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/webhooks/{webhook_id}/headers": { "get": { "operationId": "pods_webhooks_getHeaders", "summary": "Get Webhook Headers", "description": "List the names of custom HTTP headers included with deliveries to this pod-scoped webhook.\nHeader values are write-only and are never returned.", "tags": [ "pods > webhooks" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookHeaderNamesResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "pods_webhooks_updateHeaders", "summary": "Update Webhook Headers", "description": "Atomically set, replace, or remove custom HTTP headers included with deliveries to this\npod-scoped webhook. Header values remain write-only.", "tags": [ "pods > webhooks" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks:WebhookId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Response with status 204", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_webhooks:UpdateWebhookHeadersRequest" } } } } } }, "/v0/pods/{pod_id}/domains": { "get": { "operationId": "pods_domains_list", "summary": "List Domains", "description": "**CLI:**\n```bash\nagentmail pods domains list --pod-id \n```", "tags": [ "pods > domains" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "ascending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Ascending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:ListDomainsResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "post": { "operationId": "pods_domains_create", "summary": "Create Domain", "description": "**CLI:**\n```bash\nagentmail pods domains create --pod-id --domain example.com\n```", "tags": [ "pods > domains" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:Domain" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:CreateDomainRequest" } } } } } }, "/v0/pods/{pod_id}/domains/{domain_id}": { "get": { "operationId": "pods_domains_get", "summary": "Get Domain", "description": "**CLI:**\n```bash\nagentmail pods domains get --pod-id --domain-id \n```", "tags": [ "pods > domains" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:Domain" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "patch": { "operationId": "pods_domains_update", "summary": "Update Domain", "description": "**CLI:**\n```bash\nagentmail pods domains update --pod-id --domain-id \n```", "tags": [ "pods > domains" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:Domain" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_domains:UpdateDomainRequest" } } } } }, "delete": { "operationId": "pods_domains_delete", "summary": "Delete Domain", "description": "**CLI:**\n```bash\nagentmail pods domains delete --pod-id --domain-id \n```", "tags": [ "pods > domains" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/domains/{domain_id}/zone-file": { "get": { "operationId": "pods_domains_getZoneFile", "summary": "Get Zone File", "description": "**CLI:**\n```bash\nagentmail pods domains get-zone-file --pod-id --domain-id \n```", "tags": [ "pods > domains" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/domains/{domain_id}/verify": { "post": { "operationId": "pods_domains_verify", "summary": "Verify Domain", "description": "**CLI:**\n```bash\nagentmail pods domains verify --pod-id --domain-id \n```", "tags": [ "pods > domains" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_domains:DomainId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/lists/{direction}/{type}": { "get": { "operationId": "pods_lists_list", "summary": "List Entries", "description": "**CLI:**\n```bash\nagentmail pods lists list --pod-id --direction --type \n```", "tags": [ "pods > lists" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:PodListListEntriesResponse" } } } } } }, "post": { "operationId": "pods_lists_create", "summary": "Create List Entry", "description": "**CLI:**\n```bash\nagentmail pods lists create --pod-id --direction --type --entry user@example.com\n```", "tags": [ "pods > lists" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:PodListEntry" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:CreateListEntryRequest" } } } } } }, "/v0/pods/{pod_id}/lists/{direction}/{type}/{entry}": { "get": { "operationId": "pods_lists_get", "summary": "Get List Entry", "description": "**CLI:**\n```bash\nagentmail pods lists get --pod-id --direction --type --entry \n```", "tags": [ "pods > lists" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "entry", "in": "path", "description": "Email address or domain.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_lists:PodListEntry" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "delete": { "operationId": "pods_lists_delete", "summary": "Delete List Entry", "description": "**CLI:**\n```bash\nagentmail pods lists delete --pod-id --direction --type --entry \n```", "tags": [ "pods > lists" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "direction", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:Direction" } }, { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_lists:ListType" } }, { "name": "entry", "in": "path", "description": "Email address or domain.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/metrics/events": { "get": { "operationId": "pods_metrics_queryEvents", "summary": "Query Events", "description": "Counts of email events (sent, delivered, bounced, etc.) over time for\nthe pod. Defaults to the last 24 hours; `start` must be within the last\n90 days, and a future `end` is clamped to now. Omit `period` for\nindividual event counts, or set it to sum counts into buckets of that\nmany seconds.\n\n**CLI:**\n```bash\nagentmail pods metrics query-events --pod-id \n```", "tags": [ "pods > metrics" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "event_types", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricEventTypes" } }, { "name": "start", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Start" } }, { "name": "end", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:End" } }, { "name": "period", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Period" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricLimit" } }, { "name": "descending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Descending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_metrics:QueryMetricsResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/metrics/usage": { "get": { "operationId": "pods_metrics_queryUsage", "summary": "Query Usage", "description": "Cumulative usage series for the pod. Each point is the running total of\nthe usage type at that timestamp, not the change within the bucket.\nPod-scoped queries carry every usage type except `pod_count`; requested\ntypes that don't apply to the scope are ignored. Defaults to the last\n24 hours; `start` must be within the last 90 days, and a future `end`\nis clamped to now. The range divided by `period` must not exceed 1000\nbuckets.", "tags": [ "pods > metrics" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "usage_types", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:UsageTypes" } }, { "name": "start", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Start" } }, { "name": "end", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:End" } }, { "name": "period", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Period" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:MetricLimit" } }, { "name": "descending", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_metrics:Descending" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_metrics:QueryUsageResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } } } } }, "/v0/pods/{pod_id}/api-keys": { "get": { "operationId": "pods_apiKeys_list", "summary": "List API Keys", "description": "**CLI:**\n```bash\nagentmail pods api-keys list --pod-id \n```", "tags": [ "pods > api-keys" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:Limit" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/type_:PageToken" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:ListApiKeysResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } }, "post": { "operationId": "pods_apiKeys_create", "summary": "Create API Key", "description": "**CLI:**\n```bash\nagentmail pods api-keys create --pod-id --name \"My Key\"\n```", "tags": [ "pods > api-keys" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:CreateApiKeyResponse" } } } }, "400": { "description": "Error response with status 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ValidationErrorResponse" } } } }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_api-keys:CreateApiKeyRequest" } } } } } }, "/v0/pods/{pod_id}/api-keys/{api_key_id}": { "delete": { "operationId": "pods_apiKeys_delete", "summary": "Delete API Key", "description": "**CLI:**\n```bash\nagentmail pods api-keys delete --pod-id --api-key-id \n```", "tags": [ "pods > api-keys" ], "parameters": [ { "name": "pod_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_pods:PodId" } }, { "name": "api_key_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/type_api-keys:ApiKeyId" } }, { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "404": { "description": "Error response with status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_:ErrorResponse" } } } } } } }, "/v0/organizations": { "get": { "operationId": "organizations_get", "summary": "Get Organization", "description": "Returns the organization for the authenticated API key (usage limits, counts, and billing metadata).\n\n**CLI:**\n```bash\nagentmail organizations get\n```", "tags": [ "organizations" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_organizations:Organization" } } } } } } }, "/v0/auth/me": { "get": { "operationId": "auth_me", "summary": "Who Am I", "description": "Returns the identity and scope of the authenticated credential. Useful when a client holds a pod-scoped or inbox-scoped API key and needs to discover the parent organization, pod, or inbox without prior knowledge.\n\n**CLI:**\n```bash\nagentmail auth me\n```", "tags": [ "auth" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response with status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_auth:Identity" } } } } } } } }, "servers": [ { "url": "https://api.agentmail.to", "description": "prod" }, { "url": "https://x402.api.agentmail.to", "description": "prod-x402" }, { "url": "https://mpp.api.agentmail.to", "description": "prod-mpp" }, { "url": "https://api.agentmail.eu", "description": "eu-prod" } ], "webhooks": { "message-received": { "post": { "operationId": "message-received", "summary": "Message Received", "parameters": [ { "name": "svix-id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixId" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixSignature" } }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixTimestamp" } } ], "responses": { "200": { "description": "Webhook received successfully" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_events:MessageReceivedEvent" } } } } } }, "message-sent": { "post": { "operationId": "message-sent", "summary": "Message Sent", "parameters": [ { "name": "svix-id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixId" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixSignature" } }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixTimestamp" } } ], "responses": { "200": { "description": "Webhook received successfully" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_events:MessageSentEvent" } } } } } }, "message-delivered": { "post": { "operationId": "message-delivered", "summary": "Message Delivered", "parameters": [ { "name": "svix-id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixId" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixSignature" } }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixTimestamp" } } ], "responses": { "200": { "description": "Webhook received successfully" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_events:MessageDeliveredEvent" } } } } } }, "message-bounced": { "post": { "operationId": "message-bounced", "summary": "Message Bounced", "parameters": [ { "name": "svix-id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixId" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixSignature" } }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixTimestamp" } } ], "responses": { "200": { "description": "Webhook received successfully" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_events:MessageBouncedEvent" } } } } } }, "message-complained": { "post": { "operationId": "message-complained", "summary": "Message Complained", "parameters": [ { "name": "svix-id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixId" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixSignature" } }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixTimestamp" } } ], "responses": { "200": { "description": "Webhook received successfully" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_events:MessageComplainedEvent" } } } } } }, "message-rejected": { "post": { "operationId": "message-rejected", "summary": "Message Rejected", "parameters": [ { "name": "svix-id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixId" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixSignature" } }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixTimestamp" } } ], "responses": { "200": { "description": "Webhook received successfully" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_events:MessageRejectedEvent" } } } } } }, "message-opened": { "post": { "operationId": "message-opened", "summary": "Message Opened", "parameters": [ { "name": "svix-id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixId" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixSignature" } }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixTimestamp" } } ], "responses": { "200": { "description": "Webhook received successfully" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_events:MessageOpenedEvent" } } } } } }, "domain-verified": { "post": { "operationId": "domain-verified", "summary": "Domain Verified", "parameters": [ { "name": "svix-id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixId" } }, { "name": "svix-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixSignature" } }, { "name": "svix-timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/type_webhooks/events:SvixTimestamp" } } ], "responses": { "200": { "description": "Webhook received successfully" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/type_events:DomainVerifiedEvent" } } } } } } }, "components": { "schemas": { "type_agent:AgentSignupRequest": { "type": "object", "properties": { "human_email": { "type": "string", "description": "Email address of the human who owns the agent. A 6-digit OTP will be sent to this address." }, "username": { "type": "string", "description": "Username for the auto-created inbox (e.g. \"my-agent\" creates my-agent@agentmail.to)." }, "source": { "type": "string", "description": "The SDK, framework, or platform issuing this sign-up (e.g. `agentmail-python`, `agentmail-cli`, `agentmail-mcp`).\nIdentifies the caller — answers \"who is signing up\".\nMax 2048 characters." }, "referrer": { "type": "string", "description": "The channel that drove this sign-up — where the agent or its developer discovered AgentMail\n(e.g. `agent.email`, a partner URL, a campaign tag). Answers \"where did this sign-up come from\".\nMax 2048 characters." } }, "required": [ "human_email", "username" ], "description": "Request body to sign up an agent.", "title": "AgentSignupRequest" }, "type_agent:AgentSignupResponse": { "type": "object", "properties": { "organization_id": { "type": "string", "description": "ID of the created organization." }, "inbox_id": { "type": "string", "description": "ID of the auto-created inbox." }, "api_key": { "type": "string", "description": "API key for authenticating subsequent requests. Store this securely, it cannot be retrieved again." } }, "required": [ "organization_id", "inbox_id", "api_key" ], "description": "Response after successful agent sign-up.", "title": "AgentSignupResponse" }, "type_:ErrorName": { "type": "string", "description": "Name of error.", "title": "ErrorName" }, "type_:ErrorCode": { "type": "string", "description": "Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.", "title": "ErrorCode" }, "type_:ErrorMessage": { "type": "string", "description": "Error message.", "title": "ErrorMessage" }, "type_:ErrorFix": { "type": "string", "description": "The concrete next action that resolves the error.", "title": "ErrorFix" }, "type_:ErrorDocs": { "type": "string", "description": "Link to the error reference entry for this code.", "title": "ErrorDocs" }, "type_:ValidationErrorResponse": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/type_:ErrorName" }, "code": { "$ref": "#/components/schemas/type_:ErrorCode" }, "message": { "$ref": "#/components/schemas/type_:ErrorMessage" }, "errors": { "description": "Validation errors. Each entry has a path and a message identifying the invalid field." }, "fix": { "$ref": "#/components/schemas/type_:ErrorFix" }, "docs": { "$ref": "#/components/schemas/type_:ErrorDocs" } }, "required": [ "name", "errors" ], "title": "ValidationErrorResponse" }, "type_agent:AgentVerifyRequest": { "type": "object", "properties": { "otp_code": { "type": "string", "description": "6-digit verification code sent to the human's email address." } }, "required": [ "otp_code" ], "description": "Request body to verify an agent with an OTP code.", "title": "AgentVerifyRequest" }, "type_agent:AgentVerifyResponse": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "Whether the organization was verified." } }, "required": [ "verified" ], "description": "Response after successful agent verification.", "title": "AgentVerifyResponse" }, "type_:Limit": { "type": "integer", "description": "Limit of number of items returned.", "title": "Limit" }, "type_:PageToken": { "type": "string", "description": "Page token for pagination.", "title": "PageToken" }, "type_:Ascending": { "type": "boolean", "description": "Sort in ascending temporal order.", "title": "Ascending" }, "type_:Count": { "type": "integer", "description": "Number of items returned.", "title": "Count" }, "type_pods:PodId": { "type": "string", "description": "ID of pod.", "title": "PodId" }, "type_inboxes:InboxId": { "type": "string", "description": "The ID of the inbox.", "title": "InboxId" }, "type_inboxes:Email": { "type": "string", "description": "Email address of the inbox.", "title": "Email" }, "type_inboxes:DisplayName": { "type": "string", "description": "Display name: `Display Name `.", "title": "DisplayName" }, "type_inboxes:ClientId": { "type": "string", "description": "Client ID of inbox.", "title": "ClientId" }, "type_inboxes:MetadataValue": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ], "description": "A metadata value. May be a string, number, or boolean.", "title": "MetadataValue" }, "type_inboxes:Metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/type_inboxes:MetadataValue" }, "description": "Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and\nstring values are each limited to 256 characters. When updating metadata,\nsend a key with a null value to remove that key.", "title": "Metadata" }, "type_inboxes:Inbox": { "type": "object", "properties": { "pod_id": { "$ref": "#/components/schemas/type_pods:PodId" }, "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "email": { "$ref": "#/components/schemas/type_inboxes:Email" }, "display_name": { "$ref": "#/components/schemas/type_inboxes:DisplayName" }, "client_id": { "$ref": "#/components/schemas/type_inboxes:ClientId" }, "metadata": { "$ref": "#/components/schemas/type_inboxes:Metadata", "description": "Custom metadata attached to the inbox." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time at which inbox was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which inbox was created." } }, "required": [ "pod_id", "inbox_id", "email", "updated_at", "created_at" ], "title": "Inbox" }, "type_inboxes:ListInboxesResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "inboxes": { "type": "array", "items": { "$ref": "#/components/schemas/type_inboxes:Inbox" }, "description": "Ordered by `created_at` descending." } }, "required": [ "count", "inboxes" ], "title": "ListInboxesResponse" }, "type_inboxes:SearchInboxesResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "inboxes": { "type": "array", "items": { "$ref": "#/components/schemas/type_inboxes:Inbox" }, "description": "Ordered by relevance, best match first." } }, "required": [ "count", "inboxes" ], "title": "SearchInboxesResponse" }, "type_:ErrorResponse": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/type_:ErrorName" }, "code": { "$ref": "#/components/schemas/type_:ErrorCode" }, "message": { "$ref": "#/components/schemas/type_:ErrorMessage" }, "fix": { "$ref": "#/components/schemas/type_:ErrorFix" }, "docs": { "$ref": "#/components/schemas/type_:ErrorDocs" } }, "required": [ "name", "message" ], "title": "ErrorResponse" }, "type_inboxes:CreateInboxRequest": { "type": "object", "properties": { "username": { "type": "string", "description": "Username of address. Randomly generated if not specified." }, "domain": { "type": "string", "description": "Domain of address. Must be a verified domain, or any subdomain of a\nverified domain that has subdomains enabled (e.g., `bot.example.com`).\nDefaults to `agentmail.to`." }, "display_name": { "$ref": "#/components/schemas/type_inboxes:DisplayName" }, "client_id": { "$ref": "#/components/schemas/type_inboxes:ClientId" }, "metadata": { "$ref": "#/components/schemas/type_inboxes:Metadata", "description": "Custom metadata to attach to the inbox." } }, "title": "CreateInboxRequest" }, "type_inboxes:UpdateMetadata": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/type_inboxes:MetadataValue" }, { "type": "null" } ] }, "description": "Custom key-value pairs to merge into the inbox's existing metadata. A\nvalue may be a string, number, boolean, or null. Setting a key to null\nremoves it. Up to 256 keys; keys and string values are each limited to\n256 characters.", "title": "UpdateMetadata" }, "type_inboxes:UpdateInboxRequest": { "type": "object", "properties": { "display_name": { "$ref": "#/components/schemas/type_inboxes:DisplayName" }, "metadata": { "oneOf": [ { "$ref": "#/components/schemas/type_inboxes:UpdateMetadata" }, { "type": "null" } ], "description": "Metadata to merge into the inbox's existing metadata. Keys you include\nare added or overwritten; keys you omit are left unchanged. To remove a\nsingle key, send it with a null value. To clear all metadata, send\n`metadata` as null. Sending an empty object is rejected; use null to\nclear. Each update must include at least one of `display_name` or\n`metadata`." } }, "title": "UpdateInboxRequest" }, "type_:Labels": { "type": "array", "items": { "type": "string" }, "description": "Labels to filter by.", "title": "Labels" }, "type_:Before": { "type": "string", "format": "date-time", "description": "Timestamp before which to filter by.", "title": "Before" }, "type_:After": { "type": "string", "format": "date-time", "description": "Timestamp after which to filter by.", "title": "After" }, "type_:IncludeSpam": { "type": "boolean", "description": "Include spam in results.", "title": "IncludeSpam" }, "type_:IncludeBlocked": { "type": "boolean", "description": "Include blocked in results.", "title": "IncludeBlocked" }, "type_:IncludeUnauthenticated": { "type": "boolean", "description": "Include unauthenticated in results.", "title": "IncludeUnauthenticated" }, "type_:IncludeTrash": { "type": "boolean", "description": "Include trash in results.", "title": "IncludeTrash" }, "type_threads:ThreadId": { "type": "string", "description": "ID of thread.", "title": "ThreadId" }, "type_threads:ThreadLabels": { "type": "array", "items": { "type": "string" }, "description": "Labels of thread.", "title": "ThreadLabels" }, "type_threads:ThreadTimestamp": { "type": "string", "format": "date-time", "description": "Timestamp of last sent or received message.", "title": "ThreadTimestamp" }, "type_threads:ThreadReceivedTimestamp": { "type": "string", "format": "date-time", "description": "Timestamp of last received message.", "title": "ThreadReceivedTimestamp" }, "type_threads:ThreadSentTimestamp": { "type": "string", "format": "date-time", "description": "Timestamp of last sent message.", "title": "ThreadSentTimestamp" }, "type_threads:ThreadSenders": { "type": "array", "items": { "type": "string" }, "description": "Senders in thread. In format `username@domain.com` or `Display Name `.", "title": "ThreadSenders" }, "type_threads:ThreadRecipients": { "type": "array", "items": { "type": "string" }, "description": "Recipients in thread. In format `username@domain.com` or `Display Name `.", "title": "ThreadRecipients" }, "type_threads:ThreadSubject": { "type": "string", "description": "Subject of thread.", "title": "ThreadSubject" }, "type_threads:ThreadPreview": { "type": "string", "description": "Text preview of last message in thread.", "title": "ThreadPreview" }, "type_attachments:AttachmentId": { "type": "string", "description": "ID of attachment.", "title": "AttachmentId" }, "type_attachments:AttachmentFilename": { "type": "string", "description": "Filename of attachment.", "title": "AttachmentFilename" }, "type_attachments:AttachmentSize": { "type": "integer", "description": "Size of attachment in bytes.", "title": "AttachmentSize" }, "type_attachments:AttachmentContentType": { "type": "string", "description": "Content type of attachment.", "title": "AttachmentContentType" }, "type_attachments:AttachmentContentDisposition": { "type": "string", "enum": [ "inline", "attachment" ], "description": "Content disposition of attachment.", "title": "AttachmentContentDisposition" }, "type_attachments:AttachmentContentId": { "type": "string", "description": "Content ID of attachment.", "title": "AttachmentContentId" }, "type_attachments:Attachment": { "type": "object", "properties": { "attachment_id": { "$ref": "#/components/schemas/type_attachments:AttachmentId" }, "filename": { "$ref": "#/components/schemas/type_attachments:AttachmentFilename" }, "size": { "$ref": "#/components/schemas/type_attachments:AttachmentSize" }, "content_type": { "$ref": "#/components/schemas/type_attachments:AttachmentContentType" }, "content_disposition": { "$ref": "#/components/schemas/type_attachments:AttachmentContentDisposition" }, "content_id": { "$ref": "#/components/schemas/type_attachments:AttachmentContentId" } }, "required": [ "attachment_id", "size" ], "title": "Attachment" }, "type_threads:ThreadAttachments": { "type": "array", "items": { "$ref": "#/components/schemas/type_attachments:Attachment" }, "description": "Attachments in thread.", "title": "ThreadAttachments" }, "type_threads:ThreadLastMessageId": { "type": "string", "description": "ID of last message in thread.", "title": "ThreadLastMessageId" }, "type_threads:ThreadMessageCount": { "type": "integer", "description": "Number of messages in thread.", "title": "ThreadMessageCount" }, "type_threads:ThreadSize": { "type": "integer", "description": "Size of thread in bytes.", "title": "ThreadSize" }, "type_threads:ThreadUpdatedAt": { "type": "string", "format": "date-time", "description": "Time at which thread was last updated.", "title": "ThreadUpdatedAt" }, "type_threads:ThreadCreatedAt": { "type": "string", "format": "date-time", "description": "Time at which thread was created.", "title": "ThreadCreatedAt" }, "type_threads:ThreadItem": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "labels": { "$ref": "#/components/schemas/type_threads:ThreadLabels" }, "timestamp": { "$ref": "#/components/schemas/type_threads:ThreadTimestamp" }, "received_timestamp": { "$ref": "#/components/schemas/type_threads:ThreadReceivedTimestamp" }, "sent_timestamp": { "$ref": "#/components/schemas/type_threads:ThreadSentTimestamp" }, "senders": { "$ref": "#/components/schemas/type_threads:ThreadSenders" }, "recipients": { "$ref": "#/components/schemas/type_threads:ThreadRecipients" }, "subject": { "$ref": "#/components/schemas/type_threads:ThreadSubject" }, "preview": { "$ref": "#/components/schemas/type_threads:ThreadPreview" }, "attachments": { "$ref": "#/components/schemas/type_threads:ThreadAttachments" }, "last_message_id": { "$ref": "#/components/schemas/type_threads:ThreadLastMessageId" }, "message_count": { "$ref": "#/components/schemas/type_threads:ThreadMessageCount" }, "size": { "$ref": "#/components/schemas/type_threads:ThreadSize" }, "updated_at": { "$ref": "#/components/schemas/type_threads:ThreadUpdatedAt" }, "created_at": { "$ref": "#/components/schemas/type_threads:ThreadCreatedAt" } }, "required": [ "inbox_id", "thread_id", "labels", "timestamp", "senders", "recipients", "last_message_id", "message_count", "size", "updated_at", "created_at" ], "title": "ThreadItem" }, "type_threads:ListThreadsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "threads": { "type": "array", "items": { "$ref": "#/components/schemas/type_threads:ThreadItem" }, "description": "Ordered by `timestamp` descending." } }, "required": [ "count", "threads" ], "title": "ListThreadsResponse" }, "type_:Query": { "type": "string", "description": "Full-text search query. Matched against the sender, recipients, and\nsubject (substring) and the message body (tokenized full text).", "title": "Query" }, "type_threads:SearchThreadHighlights": { "type": "object", "properties": { "from": { "type": "array", "items": { "type": "string" }, "description": "Matched fragments from a sender address in the thread." }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "Matched fragments from a recipient address in the thread (to, cc, or bcc)." }, "subject": { "type": "array", "items": { "type": "string" }, "description": "Matched fragments from the subject." }, "text": { "type": "array", "items": { "type": "string" }, "description": "Matched fragments from a message body in the thread." } }, "description": "Matched fragments per field on a thread search result, with matched terms\nwrapped in `**`. A field key is present only when the query matched that\nfield, so the present keys also tell you which fields produced the hit.", "title": "SearchThreadHighlights" }, "type_threads:SearchThreadItem": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "labels": { "$ref": "#/components/schemas/type_threads:ThreadLabels" }, "timestamp": { "$ref": "#/components/schemas/type_threads:ThreadTimestamp" }, "received_timestamp": { "$ref": "#/components/schemas/type_threads:ThreadReceivedTimestamp" }, "sent_timestamp": { "$ref": "#/components/schemas/type_threads:ThreadSentTimestamp" }, "senders": { "$ref": "#/components/schemas/type_threads:ThreadSenders" }, "recipients": { "$ref": "#/components/schemas/type_threads:ThreadRecipients" }, "subject": { "$ref": "#/components/schemas/type_threads:ThreadSubject" }, "preview": { "$ref": "#/components/schemas/type_threads:ThreadPreview" }, "attachments": { "$ref": "#/components/schemas/type_threads:ThreadAttachments" }, "last_message_id": { "$ref": "#/components/schemas/type_threads:ThreadLastMessageId" }, "message_count": { "$ref": "#/components/schemas/type_threads:ThreadMessageCount" }, "size": { "$ref": "#/components/schemas/type_threads:ThreadSize" }, "updated_at": { "$ref": "#/components/schemas/type_threads:ThreadUpdatedAt" }, "created_at": { "$ref": "#/components/schemas/type_threads:ThreadCreatedAt" }, "highlights": { "$ref": "#/components/schemas/type_threads:SearchThreadHighlights", "description": "Matched fragments per field. Present only when the query matched an indexed field." } }, "required": [ "inbox_id", "thread_id", "labels", "timestamp", "senders", "recipients", "last_message_id", "message_count", "size", "updated_at", "created_at" ], "title": "SearchThreadItem" }, "type_threads:SearchThreadsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "threads": { "type": "array", "items": { "$ref": "#/components/schemas/type_threads:SearchThreadItem" }, "description": "Ordered by relevance, best match first." } }, "required": [ "count", "threads" ], "title": "SearchThreadsResponse" }, "type_messages:MessageId": { "type": "string", "description": "ID of message.", "title": "MessageId" }, "type_messages:MessageLabels": { "type": "array", "items": { "type": "string" }, "description": "Labels of message.", "title": "MessageLabels" }, "type_messages:MessageTimestamp": { "type": "string", "format": "date-time", "description": "Time at which message was sent or drafted.", "title": "MessageTimestamp" }, "type_messages:MessageFrom": { "type": "string", "description": "Address of sender. In format `username@domain.com` or `Display Name `.", "title": "MessageFrom" }, "type_messages:MessageTo": { "type": "array", "items": { "type": "string" }, "description": "Addresses of recipients. In format `username@domain.com` or `Display Name `.", "title": "MessageTo" }, "type_messages:MessageCc": { "type": "array", "items": { "type": "string" }, "description": "Addresses of CC recipients. In format `username@domain.com` or `Display Name `.", "title": "MessageCc" }, "type_messages:MessageBcc": { "type": "array", "items": { "type": "string" }, "description": "Addresses of BCC recipients. In format `username@domain.com` or `Display Name `.", "title": "MessageBcc" }, "type_messages:MessageSubject": { "type": "string", "description": "Subject of message.", "title": "MessageSubject" }, "type_messages:MessagePreview": { "type": "string", "description": "Text preview of message.", "title": "MessagePreview" }, "type_messages:MessageText": { "type": "string", "description": "Plain text body of message.", "title": "MessageText" }, "type_messages:MessageHtml": { "type": "string", "description": "HTML body of message.", "title": "MessageHtml" }, "type_messages:MessageAttachments": { "type": "array", "items": { "$ref": "#/components/schemas/type_attachments:Attachment" }, "description": "Attachments in message.", "title": "MessageAttachments" }, "type_messages:MessageInReplyTo": { "type": "string", "description": "ID of message being replied to.", "title": "MessageInReplyTo" }, "type_messages:MessageReferences": { "type": "array", "items": { "type": "string" }, "description": "IDs of previous messages in thread.", "title": "MessageReferences" }, "type_messages:MessageHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers in message.", "title": "MessageHeaders" }, "type_messages:MessageSize": { "type": "integer", "description": "Size of message in bytes.", "title": "MessageSize" }, "type_messages:MessageUpdatedAt": { "type": "string", "format": "date-time", "description": "Time at which message was last updated.", "title": "MessageUpdatedAt" }, "type_messages:MessageCreatedAt": { "type": "string", "format": "date-time", "description": "Time at which message was created.", "title": "MessageCreatedAt" }, "type_messages:Message": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "labels": { "$ref": "#/components/schemas/type_messages:MessageLabels" }, "timestamp": { "$ref": "#/components/schemas/type_messages:MessageTimestamp" }, "from": { "$ref": "#/components/schemas/type_messages:MessageFrom" }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "Reply-to addresses. In format `username@domain.com` or `Display Name `." }, "to": { "$ref": "#/components/schemas/type_messages:MessageTo" }, "cc": { "$ref": "#/components/schemas/type_messages:MessageCc" }, "bcc": { "$ref": "#/components/schemas/type_messages:MessageBcc" }, "subject": { "$ref": "#/components/schemas/type_messages:MessageSubject" }, "preview": { "$ref": "#/components/schemas/type_messages:MessagePreview" }, "text": { "$ref": "#/components/schemas/type_messages:MessageText" }, "html": { "$ref": "#/components/schemas/type_messages:MessageHtml" }, "extracted_text": { "type": "string", "description": "Extracted new text content." }, "extracted_html": { "type": "string", "description": "Extracted new HTML content." }, "attachments": { "$ref": "#/components/schemas/type_messages:MessageAttachments" }, "in_reply_to": { "$ref": "#/components/schemas/type_messages:MessageInReplyTo" }, "references": { "$ref": "#/components/schemas/type_messages:MessageReferences" }, "headers": { "$ref": "#/components/schemas/type_messages:MessageHeaders" }, "size": { "$ref": "#/components/schemas/type_messages:MessageSize" }, "updated_at": { "$ref": "#/components/schemas/type_messages:MessageUpdatedAt" }, "created_at": { "$ref": "#/components/schemas/type_messages:MessageCreatedAt" } }, "required": [ "inbox_id", "thread_id", "message_id", "labels", "timestamp", "from", "to", "size", "updated_at", "created_at" ], "title": "Message" }, "type_threads:Thread": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "labels": { "$ref": "#/components/schemas/type_threads:ThreadLabels" }, "timestamp": { "$ref": "#/components/schemas/type_threads:ThreadTimestamp" }, "received_timestamp": { "$ref": "#/components/schemas/type_threads:ThreadReceivedTimestamp" }, "sent_timestamp": { "$ref": "#/components/schemas/type_threads:ThreadSentTimestamp" }, "senders": { "$ref": "#/components/schemas/type_threads:ThreadSenders" }, "recipients": { "$ref": "#/components/schemas/type_threads:ThreadRecipients" }, "subject": { "$ref": "#/components/schemas/type_threads:ThreadSubject" }, "preview": { "$ref": "#/components/schemas/type_threads:ThreadPreview" }, "attachments": { "$ref": "#/components/schemas/type_threads:ThreadAttachments" }, "last_message_id": { "$ref": "#/components/schemas/type_threads:ThreadLastMessageId" }, "message_count": { "$ref": "#/components/schemas/type_threads:ThreadMessageCount" }, "size": { "$ref": "#/components/schemas/type_threads:ThreadSize" }, "updated_at": { "$ref": "#/components/schemas/type_threads:ThreadUpdatedAt" }, "created_at": { "$ref": "#/components/schemas/type_threads:ThreadCreatedAt" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/type_messages:Message" }, "description": "Messages in thread. Ordered by `timestamp` ascending." } }, "required": [ "inbox_id", "thread_id", "labels", "timestamp", "senders", "recipients", "last_message_id", "message_count", "size", "updated_at", "created_at", "messages" ], "title": "Thread" }, "type_attachments:AttachmentResponse": { "type": "object", "properties": { "attachment_id": { "$ref": "#/components/schemas/type_attachments:AttachmentId" }, "filename": { "$ref": "#/components/schemas/type_attachments:AttachmentFilename" }, "size": { "$ref": "#/components/schemas/type_attachments:AttachmentSize" }, "content_type": { "$ref": "#/components/schemas/type_attachments:AttachmentContentType" }, "content_disposition": { "$ref": "#/components/schemas/type_attachments:AttachmentContentDisposition" }, "content_id": { "$ref": "#/components/schemas/type_attachments:AttachmentContentId" }, "download_url": { "type": "string", "description": "URL to download the attachment." }, "expires_at": { "type": "string", "format": "date-time", "description": "Time at which the download URL expires." } }, "required": [ "attachment_id", "size", "download_url", "expires_at" ], "title": "AttachmentResponse" }, "type_threads:UpdateThreadRequest": { "type": "object", "properties": { "add_labels": { "type": "array", "items": { "type": "string" }, "description": "Labels to add to thread. Cannot be system labels." }, "remove_labels": { "type": "array", "items": { "type": "string" }, "description": "Labels to remove from thread. Cannot be system labels. Takes priority over `add_labels` (in the event of duplicate labels passed in)." } }, "title": "UpdateThreadRequest" }, "type_threads:UpdateThreadResponse": { "type": "object", "properties": { "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "labels": { "$ref": "#/components/schemas/type_threads:ThreadLabels" } }, "required": [ "thread_id", "labels" ], "title": "UpdateThreadResponse" }, "type_messages:MessageItem": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "labels": { "$ref": "#/components/schemas/type_messages:MessageLabels" }, "timestamp": { "$ref": "#/components/schemas/type_messages:MessageTimestamp" }, "from": { "$ref": "#/components/schemas/type_messages:MessageFrom" }, "to": { "$ref": "#/components/schemas/type_messages:MessageTo" }, "cc": { "$ref": "#/components/schemas/type_messages:MessageCc" }, "bcc": { "$ref": "#/components/schemas/type_messages:MessageBcc" }, "subject": { "$ref": "#/components/schemas/type_messages:MessageSubject" }, "preview": { "$ref": "#/components/schemas/type_messages:MessagePreview" }, "attachments": { "$ref": "#/components/schemas/type_messages:MessageAttachments" }, "in_reply_to": { "$ref": "#/components/schemas/type_messages:MessageInReplyTo" }, "references": { "$ref": "#/components/schemas/type_messages:MessageReferences" }, "headers": { "$ref": "#/components/schemas/type_messages:MessageHeaders" }, "size": { "$ref": "#/components/schemas/type_messages:MessageSize" }, "updated_at": { "$ref": "#/components/schemas/type_messages:MessageUpdatedAt" }, "created_at": { "$ref": "#/components/schemas/type_messages:MessageCreatedAt" } }, "required": [ "inbox_id", "thread_id", "message_id", "labels", "timestamp", "from", "to", "size", "updated_at", "created_at" ], "title": "MessageItem" }, "type_messages:ListMessagesResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/type_messages:MessageItem" }, "description": "Ordered by `timestamp` descending." } }, "required": [ "count", "messages" ], "title": "ListMessagesResponse" }, "type_messages:SearchMessageHighlights": { "type": "object", "properties": { "from": { "type": "array", "items": { "type": "string" }, "description": "Matched fragments from the sender address." }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "Matched fragments from the recipient addresses (to, cc, or bcc)." }, "subject": { "type": "array", "items": { "type": "string" }, "description": "Matched fragments from the subject." }, "text": { "type": "array", "items": { "type": "string" }, "description": "Matched fragments from the message body." } }, "description": "Matched fragments per field on a message search result, with matched terms\nwrapped in `**`. A field key is present only when the query matched that\nfield, so the present keys also tell you which fields produced the hit.", "title": "SearchMessageHighlights" }, "type_messages:SearchMessageItem": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "labels": { "$ref": "#/components/schemas/type_messages:MessageLabels" }, "timestamp": { "$ref": "#/components/schemas/type_messages:MessageTimestamp" }, "from": { "$ref": "#/components/schemas/type_messages:MessageFrom" }, "to": { "$ref": "#/components/schemas/type_messages:MessageTo" }, "cc": { "$ref": "#/components/schemas/type_messages:MessageCc" }, "bcc": { "$ref": "#/components/schemas/type_messages:MessageBcc" }, "subject": { "$ref": "#/components/schemas/type_messages:MessageSubject" }, "preview": { "$ref": "#/components/schemas/type_messages:MessagePreview" }, "attachments": { "$ref": "#/components/schemas/type_messages:MessageAttachments" }, "in_reply_to": { "$ref": "#/components/schemas/type_messages:MessageInReplyTo" }, "references": { "$ref": "#/components/schemas/type_messages:MessageReferences" }, "headers": { "$ref": "#/components/schemas/type_messages:MessageHeaders" }, "size": { "$ref": "#/components/schemas/type_messages:MessageSize" }, "updated_at": { "$ref": "#/components/schemas/type_messages:MessageUpdatedAt" }, "created_at": { "$ref": "#/components/schemas/type_messages:MessageCreatedAt" }, "highlights": { "$ref": "#/components/schemas/type_messages:SearchMessageHighlights", "description": "Matched fragments per field. Present only when the query matched an indexed field." } }, "required": [ "inbox_id", "thread_id", "message_id", "labels", "timestamp", "from", "to", "size", "updated_at", "created_at" ], "title": "SearchMessageItem" }, "type_messages:SearchMessagesResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/type_messages:SearchMessageItem" }, "description": "Ordered by relevance, best match first." } }, "required": [ "count", "messages" ], "title": "SearchMessagesResponse" }, "type_messages:BatchGetMessagesMessageIds": { "type": "array", "items": { "$ref": "#/components/schemas/type_messages:MessageId" }, "description": "IDs of messages to fetch. Maximum 500 ids per request. Duplicates are\nrejected with a validation error. IDs not found in the inbox (including\ncross-inbox or permission-restricted) are silently omitted from the\nresponse; callers detect misses by comparing `count` against `limit`.", "title": "BatchGetMessagesMessageIds" }, "type_messages:BatchGetMessagesRequest": { "type": "object", "properties": { "message_ids": { "$ref": "#/components/schemas/type_messages:BatchGetMessagesMessageIds" } }, "required": [ "message_ids" ], "title": "BatchGetMessagesRequest" }, "type_messages:BatchGetMessagesResponse": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/type_:Limit" }, "count": { "$ref": "#/components/schemas/type_:Count" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/type_messages:Message" }, "description": "Found messages. Order matches `message_ids` in the request. Body\nfields (`text`, `html`, `extracted_text`, `extracted_html`) are\nnever populated; use the single-message endpoint to retrieve bodies." } }, "required": [ "limit", "count", "messages" ], "title": "BatchGetMessagesResponse" }, "type_messages:BatchUpdateMessagesMessageIds": { "type": "array", "items": { "$ref": "#/components/schemas/type_messages:MessageId" }, "description": "IDs of messages to update. Maximum 50 ids per request. Duplicates are\nrejected with a validation error. IDs not found in the inbox (including\ncross-inbox or permission-restricted) are silently excluded from the\nupdate; callers detect exclusions by comparing `count` against `limit`.", "title": "BatchUpdateMessagesMessageIds" }, "type_messages:UpdateMessageLabels": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Label or list of labels.", "title": "UpdateMessageLabels" }, "type_messages:BatchUpdateMessagesRequest": { "type": "object", "properties": { "message_ids": { "$ref": "#/components/schemas/type_messages:BatchUpdateMessagesMessageIds" }, "add_labels": { "$ref": "#/components/schemas/type_messages:UpdateMessageLabels", "description": "Label or labels to add to every message." }, "remove_labels": { "$ref": "#/components/schemas/type_messages:UpdateMessageLabels", "description": "Label or labels to remove from every message." } }, "required": [ "message_ids" ], "title": "BatchUpdateMessagesRequest" }, "type_messages:UpdateMessageResponse": { "type": "object", "properties": { "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "labels": { "$ref": "#/components/schemas/type_messages:MessageLabels" } }, "required": [ "message_id", "labels" ], "title": "UpdateMessageResponse" }, "type_messages:BatchUpdateMessagesResponse": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/type_:Limit" }, "count": { "$ref": "#/components/schemas/type_:Count" }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/type_messages:UpdateMessageResponse" }, "description": "Updated messages with their new labels. Order matches `message_ids`\nin the request. Excluded ids are omitted, so `count` may be less than\n`limit`." } }, "required": [ "limit", "count", "updates" ], "title": "BatchUpdateMessagesResponse" }, "type_messages:RawMessageResponse": { "type": "object", "properties": { "message_id": { "$ref": "#/components/schemas/type_messages:MessageId", "description": "ID of the message." }, "size": { "$ref": "#/components/schemas/type_messages:MessageSize", "description": "Size of the raw message in bytes." }, "download_url": { "type": "string", "description": "S3 presigned URL to download the raw message. Expires at expires_at." }, "expires_at": { "type": "string", "format": "date-time", "description": "Time at which the download URL expires." } }, "required": [ "message_id", "size", "download_url", "expires_at" ], "description": "S3 presigned URL to download the raw .eml file.", "title": "RawMessageResponse" }, "type_messages:UpdateMessageRequest": { "type": "object", "properties": { "add_labels": { "$ref": "#/components/schemas/type_messages:UpdateMessageLabels", "description": "Label or labels to add to message." }, "remove_labels": { "$ref": "#/components/schemas/type_messages:UpdateMessageLabels", "description": "Label or labels to remove from message." } }, "title": "UpdateMessageRequest" }, "type_messages:Addresses": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "title": "Addresses" }, "type_messages:SendMessageReplyTo": { "$ref": "#/components/schemas/type_messages:Addresses", "description": "Reply-to address or addresses.", "title": "SendMessageReplyTo" }, "type_messages:SendMessageTo": { "$ref": "#/components/schemas/type_messages:Addresses", "description": "Recipient address or addresses.", "title": "SendMessageTo" }, "type_messages:SendMessageCc": { "$ref": "#/components/schemas/type_messages:Addresses", "description": "CC recipient address or addresses.", "title": "SendMessageCc" }, "type_messages:SendMessageBcc": { "$ref": "#/components/schemas/type_messages:Addresses", "description": "BCC recipient address or addresses.", "title": "SendMessageBcc" }, "type_attachments:SendAttachment": { "type": "object", "properties": { "filename": { "$ref": "#/components/schemas/type_attachments:AttachmentFilename" }, "content_type": { "$ref": "#/components/schemas/type_attachments:AttachmentContentType" }, "content_disposition": { "$ref": "#/components/schemas/type_attachments:AttachmentContentDisposition" }, "content_id": { "$ref": "#/components/schemas/type_attachments:AttachmentContentId" }, "content": { "type": "string", "description": "Base64 encoded content of the attachment. The entire request, including the message body and all attachments, is limited to 6 MB." }, "url": { "type": "string", "description": "URL that AgentMail can download without custom authentication headers or cookies.\nRedirects and pre-signed URLs are supported, and the final response must be a\nsuccessful 2xx response. Keep URL-backed attachments around 30 MB total per message." } }, "description": "Provide either `content` or `url` for each attachment.", "title": "SendAttachment" }, "type_messages:SendMessageAttachments": { "type": "array", "items": { "$ref": "#/components/schemas/type_attachments:SendAttachment" }, "description": "Attachments to include in message.", "title": "SendMessageAttachments" }, "type_messages:SendMessageHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers to include in message.", "title": "SendMessageHeaders" }, "type_messages:TrackOpens": { "type": "boolean", "description": "Track when this message is first opened. Requires a custom domain with tracking enabled and\nan HTML body. Opens surface as the `opened` label on the message and as a `message.opened`\nevent. One pixel is injected per message, not per recipient, so a message with several\nrecipients fires once when any of them opens it, and the event does not identify which one.", "title": "TrackOpens" }, "type_messages:SendMessageRequest": { "type": "object", "properties": { "labels": { "$ref": "#/components/schemas/type_messages:MessageLabels" }, "reply_to": { "$ref": "#/components/schemas/type_messages:SendMessageReplyTo" }, "to": { "$ref": "#/components/schemas/type_messages:SendMessageTo" }, "cc": { "$ref": "#/components/schemas/type_messages:SendMessageCc" }, "bcc": { "$ref": "#/components/schemas/type_messages:SendMessageBcc" }, "subject": { "$ref": "#/components/schemas/type_messages:MessageSubject" }, "text": { "$ref": "#/components/schemas/type_messages:MessageText" }, "html": { "$ref": "#/components/schemas/type_messages:MessageHtml" }, "attachments": { "$ref": "#/components/schemas/type_messages:SendMessageAttachments" }, "headers": { "$ref": "#/components/schemas/type_messages:SendMessageHeaders" }, "track_opens": { "$ref": "#/components/schemas/type_messages:TrackOpens" } }, "title": "SendMessageRequest" }, "type_messages:SendMessageResponse": { "type": "object", "properties": { "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" } }, "required": [ "message_id", "thread_id" ], "title": "SendMessageResponse" }, "type_messages:ReplyAll": { "type": "boolean", "description": "Reply to all recipients of the original message.", "title": "ReplyAll" }, "type_messages:ReplyToMessageRequest": { "type": "object", "properties": { "labels": { "$ref": "#/components/schemas/type_messages:MessageLabels" }, "reply_to": { "$ref": "#/components/schemas/type_messages:SendMessageReplyTo" }, "to": { "$ref": "#/components/schemas/type_messages:SendMessageTo" }, "cc": { "$ref": "#/components/schemas/type_messages:SendMessageCc" }, "bcc": { "$ref": "#/components/schemas/type_messages:SendMessageBcc" }, "reply_all": { "$ref": "#/components/schemas/type_messages:ReplyAll" }, "text": { "$ref": "#/components/schemas/type_messages:MessageText" }, "html": { "$ref": "#/components/schemas/type_messages:MessageHtml" }, "attachments": { "$ref": "#/components/schemas/type_messages:SendMessageAttachments" }, "headers": { "$ref": "#/components/schemas/type_messages:SendMessageHeaders" }, "track_opens": { "$ref": "#/components/schemas/type_messages:TrackOpens" } }, "title": "ReplyToMessageRequest" }, "type_messages:ReplyAllMessageRequest": { "type": "object", "properties": { "labels": { "$ref": "#/components/schemas/type_messages:MessageLabels" }, "reply_to": { "$ref": "#/components/schemas/type_messages:SendMessageReplyTo" }, "text": { "$ref": "#/components/schemas/type_messages:MessageText" }, "html": { "$ref": "#/components/schemas/type_messages:MessageHtml" }, "attachments": { "$ref": "#/components/schemas/type_messages:SendMessageAttachments" }, "headers": { "$ref": "#/components/schemas/type_messages:SendMessageHeaders" }, "track_opens": { "$ref": "#/components/schemas/type_messages:TrackOpens" } }, "title": "ReplyAllMessageRequest" }, "type_drafts:DraftId": { "type": "string", "description": "ID of draft.", "title": "DraftId" }, "type_drafts:DraftLabels": { "type": "array", "items": { "type": "string" }, "description": "Labels of draft.", "title": "DraftLabels" }, "type_drafts:DraftTo": { "type": "array", "items": { "type": "string" }, "description": "Addresses of recipients. In format `username@domain.com` or `Display Name `.", "title": "DraftTo" }, "type_drafts:DraftCc": { "type": "array", "items": { "type": "string" }, "description": "Addresses of CC recipients. In format `username@domain.com` or `Display Name `.", "title": "DraftCc" }, "type_drafts:DraftBcc": { "type": "array", "items": { "type": "string" }, "description": "Addresses of BCC recipients. In format `username@domain.com` or `Display Name `.", "title": "DraftBcc" }, "type_drafts:DraftSubject": { "type": "string", "description": "Subject of draft.", "title": "DraftSubject" }, "type_drafts:DraftPreview": { "type": "string", "description": "Text preview of draft.", "title": "DraftPreview" }, "type_drafts:DraftAttachments": { "type": "array", "items": { "$ref": "#/components/schemas/type_attachments:Attachment" }, "description": "Attachments in draft.", "title": "DraftAttachments" }, "type_drafts:DraftInReplyTo": { "type": "string", "description": "ID of message being replied to.", "title": "DraftInReplyTo" }, "type_drafts:DraftForwardOf": { "type": "string", "description": "ID of message being forwarded.", "title": "DraftForwardOf" }, "type_drafts:DraftSendStatus": { "type": "string", "enum": [ "scheduled", "sending", "failed" ], "description": "Schedule send status of draft.", "title": "DraftSendStatus" }, "type_drafts:DraftSendAt": { "type": "string", "format": "date-time", "description": "Time at which to schedule send draft.", "title": "DraftSendAt" }, "type_drafts:DraftUpdatedAt": { "type": "string", "format": "date-time", "description": "Time at which draft was last updated.", "title": "DraftUpdatedAt" }, "type_drafts:DraftItem": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "draft_id": { "$ref": "#/components/schemas/type_drafts:DraftId" }, "labels": { "$ref": "#/components/schemas/type_drafts:DraftLabels" }, "to": { "$ref": "#/components/schemas/type_drafts:DraftTo" }, "cc": { "$ref": "#/components/schemas/type_drafts:DraftCc" }, "bcc": { "$ref": "#/components/schemas/type_drafts:DraftBcc" }, "subject": { "$ref": "#/components/schemas/type_drafts:DraftSubject" }, "preview": { "$ref": "#/components/schemas/type_drafts:DraftPreview" }, "attachments": { "$ref": "#/components/schemas/type_drafts:DraftAttachments" }, "in_reply_to": { "$ref": "#/components/schemas/type_drafts:DraftInReplyTo" }, "forward_of": { "$ref": "#/components/schemas/type_drafts:DraftForwardOf" }, "send_status": { "$ref": "#/components/schemas/type_drafts:DraftSendStatus" }, "send_at": { "$ref": "#/components/schemas/type_drafts:DraftSendAt" }, "updated_at": { "$ref": "#/components/schemas/type_drafts:DraftUpdatedAt" } }, "required": [ "inbox_id", "draft_id", "labels", "updated_at" ], "title": "DraftItem" }, "type_drafts:ListDraftsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "drafts": { "type": "array", "items": { "$ref": "#/components/schemas/type_drafts:DraftItem" }, "description": "Ordered by `updated_at` descending." } }, "required": [ "count", "drafts" ], "title": "ListDraftsResponse" }, "type_drafts:DraftClientId": { "type": "string", "description": "Client ID of draft.", "title": "DraftClientId" }, "type_drafts:DraftReplyTo": { "type": "array", "items": { "type": "string" }, "description": "Reply-to addresses. In format `username@domain.com` or `Display Name `.", "title": "DraftReplyTo" }, "type_drafts:DraftText": { "type": "string", "description": "Plain text body of draft.", "title": "DraftText" }, "type_drafts:DraftHtml": { "type": "string", "description": "HTML body of draft.", "title": "DraftHtml" }, "type_drafts:Draft": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "draft_id": { "$ref": "#/components/schemas/type_drafts:DraftId" }, "client_id": { "$ref": "#/components/schemas/type_drafts:DraftClientId" }, "labels": { "$ref": "#/components/schemas/type_drafts:DraftLabels" }, "reply_to": { "$ref": "#/components/schemas/type_drafts:DraftReplyTo" }, "to": { "$ref": "#/components/schemas/type_drafts:DraftTo" }, "cc": { "$ref": "#/components/schemas/type_drafts:DraftCc" }, "bcc": { "$ref": "#/components/schemas/type_drafts:DraftBcc" }, "subject": { "$ref": "#/components/schemas/type_drafts:DraftSubject" }, "preview": { "$ref": "#/components/schemas/type_drafts:DraftPreview" }, "text": { "$ref": "#/components/schemas/type_drafts:DraftText" }, "html": { "$ref": "#/components/schemas/type_drafts:DraftHtml" }, "attachments": { "$ref": "#/components/schemas/type_drafts:DraftAttachments" }, "in_reply_to": { "$ref": "#/components/schemas/type_drafts:DraftInReplyTo" }, "forward_of": { "$ref": "#/components/schemas/type_drafts:DraftForwardOf" }, "references": { "type": "array", "items": { "type": "string" }, "description": "IDs of previous messages in thread." }, "send_status": { "$ref": "#/components/schemas/type_drafts:DraftSendStatus" }, "send_at": { "$ref": "#/components/schemas/type_drafts:DraftSendAt" }, "updated_at": { "$ref": "#/components/schemas/type_drafts:DraftUpdatedAt" }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which draft was created." } }, "required": [ "inbox_id", "draft_id", "labels", "updated_at", "created_at" ], "title": "Draft" }, "type_drafts:DraftReplyAll": { "type": "boolean", "description": "Reply to all recipients of the original message.", "title": "DraftReplyAll" }, "type_drafts:CreateDraftRequest": { "type": "object", "properties": { "labels": { "$ref": "#/components/schemas/type_drafts:DraftLabels" }, "reply_to": { "$ref": "#/components/schemas/type_drafts:DraftReplyTo" }, "to": { "$ref": "#/components/schemas/type_drafts:DraftTo" }, "cc": { "$ref": "#/components/schemas/type_drafts:DraftCc" }, "bcc": { "$ref": "#/components/schemas/type_drafts:DraftBcc" }, "subject": { "$ref": "#/components/schemas/type_drafts:DraftSubject" }, "text": { "$ref": "#/components/schemas/type_drafts:DraftText" }, "html": { "$ref": "#/components/schemas/type_drafts:DraftHtml" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/type_attachments:SendAttachment" }, "description": "Attachments to include in draft." }, "in_reply_to": { "$ref": "#/components/schemas/type_drafts:DraftInReplyTo" }, "forward_of": { "$ref": "#/components/schemas/type_drafts:DraftForwardOf" }, "reply_all": { "$ref": "#/components/schemas/type_drafts:DraftReplyAll" }, "send_at": { "$ref": "#/components/schemas/type_drafts:DraftSendAt" }, "client_id": { "$ref": "#/components/schemas/type_drafts:DraftClientId" } }, "description": "Body for creating a draft. Supports plain, reply, reply-all, and forward\ndrafts:\n\n- **Plain draft:** supply `to`, `subject`, `text`, etc.\n- **Reply:** set `in_reply_to` to a message ID. Recipients, subject, and\n threading are derived from that message. Set `reply_all` to address the\n whole thread (you then cannot also pass `to`, `cc`, or `bcc`).\n- **Forward:** set `forward_of` to a message ID. The subject and threading\n are derived from the source message, whose body and attachments are\n merged in at send time.\n\n`in_reply_to` and `forward_of` are mutually exclusive, and reading the\nreferenced message requires `message_read` permission.", "title": "CreateDraftRequest" }, "type_drafts:UpdateDraftRequest": { "type": "object", "properties": { "reply_to": { "oneOf": [ { "$ref": "#/components/schemas/type_drafts:DraftReplyTo" }, { "type": "null" } ] }, "to": { "oneOf": [ { "$ref": "#/components/schemas/type_drafts:DraftTo" }, { "type": "null" } ] }, "cc": { "oneOf": [ { "$ref": "#/components/schemas/type_drafts:DraftCc" }, { "type": "null" } ] }, "bcc": { "oneOf": [ { "$ref": "#/components/schemas/type_drafts:DraftBcc" }, { "type": "null" } ] }, "subject": { "oneOf": [ { "$ref": "#/components/schemas/type_drafts:DraftSubject" }, { "type": "null" } ] }, "text": { "oneOf": [ { "$ref": "#/components/schemas/type_drafts:DraftText" }, { "type": "null" } ] }, "html": { "oneOf": [ { "$ref": "#/components/schemas/type_drafts:DraftHtml" }, { "type": "null" } ] }, "add_attachments": { "type": "array", "items": { "$ref": "#/components/schemas/type_attachments:SendAttachment" }, "description": "Attachments to add to the draft." }, "remove_attachments": { "type": "array", "items": { "$ref": "#/components/schemas/type_attachments:AttachmentId" }, "description": "IDs of attachments to remove from the draft." }, "add_labels": { "$ref": "#/components/schemas/type_drafts:DraftLabels", "description": "Label or labels to add to the draft." }, "remove_labels": { "$ref": "#/components/schemas/type_drafts:DraftLabels", "description": "Label or labels to remove from the draft." }, "send_at": { "oneOf": [ { "$ref": "#/components/schemas/type_drafts:DraftSendAt" }, { "type": "null" } ] } }, "description": "Edit fields on an existing draft. A draft's kind (plain, reply, or forward)\nis fixed at creation and cannot be changed here. Omitting a field leaves it\nunchanged; passing `null` (or `[]` for a recipient field) clears it. Pass\n`send_at` to schedule or reschedule the draft, or `null` to un-schedule it.", "title": "UpdateDraftRequest" }, "type_api-keys:BrowserEnrollmentTransactionJti": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$", "minLength": 22, "maxLength": 22, "description": "Transaction identifier read from an enrollment action on exactly `https://auth.agentid.com`.", "title": "BrowserEnrollmentTransactionJti" }, "type_api-keys:CreateBrowserEnrollmentRequest": { "type": "object", "properties": { "transaction_jti": { "$ref": "#/components/schemas/type_api-keys:BrowserEnrollmentTransactionJti" } }, "required": [ "transaction_jti" ], "description": "Attach a browser enrollment intent to one pending AgentID authorization\ntransaction. The inbox is selected by the trusted path parameter, not an\nAgentID `login_hint`.", "title": "CreateBrowserEnrollmentRequest" }, "type_api-keys:BrowserEnrollmentAccepted": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ] }, "enrollment_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "integer", "minimum": 1, "description": "Unix timestamp after which the pending enrollment cannot be activated." } }, "required": [ "status", "enrollment_id", "expires_at" ], "description": "Pending enrollment receipt. The browser completes key creation and proof\non the existing AgentID page. This response contains no URL, token, or\nnavigation instruction.", "title": "BrowserEnrollmentAccepted" }, "type_webhooks:WebhookId": { "type": "string", "description": "ID of webhook.", "title": "WebhookId" }, "type_webhooks:Url": { "type": "string", "description": "URL of webhook endpoint.", "title": "Url" }, "type_events:EventType": { "type": "string", "enum": [ "message.received", "message.received.spam", "message.received.blocked", "message.received.unauthenticated", "message.sent", "message.delivered", "message.bounced", "message.complained", "message.rejected", "message.opened", "domain.verified" ], "title": "EventType" }, "type_events:EventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/type_events:EventType" }, "description": "Event types for which to send events.", "title": "EventTypes" }, "type_events:PodIds": { "type": "array", "items": { "type": "string" }, "description": "Pods for which to send events. Maximum 10 per webhook.", "title": "PodIds" }, "type_events:InboxIds": { "type": "array", "items": { "type": "string" }, "description": "Inboxes for which to send events. Maximum 10 per webhook.", "title": "InboxIds" }, "type_webhooks:ClientId": { "type": "string", "description": "Client ID of webhook.", "title": "ClientId" }, "type_webhooks:Webhook": { "type": "object", "properties": { "webhook_id": { "$ref": "#/components/schemas/type_webhooks:WebhookId" }, "url": { "$ref": "#/components/schemas/type_webhooks:Url" }, "event_types": { "$ref": "#/components/schemas/type_events:EventTypes" }, "pod_ids": { "$ref": "#/components/schemas/type_events:PodIds" }, "inbox_ids": { "$ref": "#/components/schemas/type_events:InboxIds" }, "secret": { "type": "string", "description": "Secret for webhook signature verification." }, "enabled": { "type": "boolean", "description": "Webhook is enabled." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time at which webhook was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which webhook was created." }, "client_id": { "$ref": "#/components/schemas/type_webhooks:ClientId" } }, "required": [ "webhook_id", "url", "secret", "enabled", "updated_at", "created_at" ], "title": "Webhook" }, "type_webhooks:ListWebhooksResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/type_webhooks:Webhook" }, "description": "Ordered by `created_at` descending." } }, "required": [ "count", "webhooks" ], "title": "ListWebhooksResponse" }, "type_webhooks:WebhookHeaderNamesResponse": { "type": "object", "properties": { "header_names": { "type": "array", "items": { "type": "string" }, "description": "Names of the custom delivery headers configured for this webhook. Header values are never returned." } }, "required": [ "header_names" ], "title": "WebhookHeaderNamesResponse" }, "type_webhooks:CreateWebhookEventTypes": { "$ref": "#/components/schemas/type_events:EventTypes", "description": "Full list of event types this webhook should receive. At least one type is required. Send every type you\nwant in this array (not incremental). See [Webhooks overview](https://docs.agentmail.to/webhooks-overview)\nfor spam, blocked, and unauthenticated events and required permissions.", "title": "CreateWebhookEventTypes" }, "type_webhooks:WebhookHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers to include with every delivery to this webhook. Header values are write-only:\nAgentMail never returns them from webhook read endpoints. The map must contain at least one entry\nwhen provided, and every name and value must be a valid HTTP header.", "title": "WebhookHeaders" }, "type_webhooks:CreateInboxWebhookRequest": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/type_webhooks:Url" }, "event_types": { "$ref": "#/components/schemas/type_webhooks:CreateWebhookEventTypes" }, "client_id": { "$ref": "#/components/schemas/type_webhooks:ClientId" }, "headers": { "$ref": "#/components/schemas/type_webhooks:WebhookHeaders" } }, "required": [ "url", "event_types" ], "description": "Create a webhook scoped to an inbox. The inbox comes from the path, so `inbox_ids` and `pod_ids`\nare not accepted.", "title": "CreateInboxWebhookRequest" }, "type_webhooks:UpdateWebhookEventTypes": { "$ref": "#/components/schemas/type_events:EventTypes", "description": "When you send a non-empty list, it replaces the webhook's subscribed event types in full (the same\n\"set the list\" behavior as create). It is not a merge or diff: include every event type you want after\nthe update. Sending a one-element array means the webhook will only receive that one type afterward.\nOmit this field or send an empty array to leave event types unchanged. Clearing all types with an empty\nlist is not supported. Subscribing to `message.received.spam`, `message.received.blocked`, or\n`message.received.unauthenticated` requires the matching label permission on the API key.", "title": "UpdateWebhookEventTypes" }, "type_webhooks:UpdateInboxWebhookRequest": { "type": "object", "properties": { "event_types": { "$ref": "#/components/schemas/type_webhooks:UpdateWebhookEventTypes" } }, "description": "Update an inbox-scoped webhook. It is fixed to its inbox, so only `event_types` can change.", "title": "UpdateInboxWebhookRequest" }, "type_webhooks:UpdateWebhookHeadersRequest": { "type": "object", "properties": { "headers": { "$ref": "#/components/schemas/type_webhooks:WebhookHeaders" }, "remove_headers": { "type": "array", "items": { "type": "string" }, "description": "Names of custom delivery headers to remove." } }, "description": "Set, replace, or remove custom delivery headers. Provide at least one of `headers` or\n`remove_headers`. A header cannot be set and removed in the same request, regardless of casing.", "title": "UpdateWebhookHeadersRequest" }, "type_lists:Direction": { "type": "string", "enum": [ "send", "receive", "reply" ], "description": "Direction of list entry.", "title": "Direction" }, "type_lists:ListType": { "type": "string", "enum": [ "allow", "block" ], "description": "Type of list entry.", "title": "ListType" }, "type_:OrganizationId": { "type": "string", "description": "ID of organization.", "title": "OrganizationId" }, "type_lists:EntryType": { "type": "string", "enum": [ "email", "domain" ], "description": "Whether the entry is an email address or domain.", "title": "EntryType" }, "type_lists:PodListEntry": { "type": "object", "properties": { "entry": { "type": "string", "description": "Email address or domain of list entry." }, "organization_id": { "$ref": "#/components/schemas/type_:OrganizationId" }, "reason": { "type": "string", "description": "Reason for adding the entry." }, "direction": { "$ref": "#/components/schemas/type_lists:Direction" }, "list_type": { "$ref": "#/components/schemas/type_lists:ListType" }, "entry_type": { "$ref": "#/components/schemas/type_lists:EntryType" }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which entry was created." }, "read_only": { "type": "boolean", "description": "Whether the entry is read-only and cannot be deleted via the API." }, "pod_id": { "type": "string", "description": "ID of pod." }, "inbox_id": { "type": "string", "description": "ID of inbox, if entry is inbox-scoped." } }, "required": [ "entry", "organization_id", "direction", "list_type", "entry_type", "created_at", "pod_id" ], "title": "PodListEntry" }, "type_lists:PodListListEntriesResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/type_lists:PodListEntry" }, "description": "Ordered by entry ascending." } }, "required": [ "count", "entries" ], "title": "PodListListEntriesResponse" }, "type_lists:CreateListEntryRequest": { "type": "object", "properties": { "entry": { "type": "string", "description": "Email address or domain to add." }, "reason": { "type": "string", "description": "Reason for adding the entry." } }, "required": [ "entry" ], "title": "CreateListEntryRequest" }, "type_metrics:MetricEventType": { "type": "string", "enum": [ "message.received", "message.received.spam", "message.received.blocked", "message.received.unauthenticated", "message.sent", "message.delivered", "message.bounced", "message.complained", "message.rejected", "domain.verified" ], "description": "Type of metric event.", "title": "MetricEventType" }, "type_metrics:MetricEventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/type_metrics:MetricEventType" }, "description": "List of metric event types to query.", "title": "MetricEventTypes" }, "type_metrics:Start": { "type": "string", "format": "date-time", "description": "Start timestamp for the query.", "title": "Start" }, "type_metrics:End": { "type": "string", "format": "date-time", "description": "End timestamp for the query.", "title": "End" }, "type_metrics:Period": { "type": "integer", "description": "Size of each time bucket as a whole number of seconds, between 1 and 86400.", "title": "Period" }, "type_metrics:MetricLimit": { "type": "integer", "description": "Limit on number of buckets to return.", "title": "MetricLimit" }, "type_metrics:Descending": { "type": "boolean", "description": "Sort in descending order.", "title": "Descending" }, "type_metrics:MetricBucket": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the bucket." }, "count": { "type": "integer", "description": "Count of events in the bucket." } }, "required": [ "timestamp", "count" ], "title": "MetricBucket" }, "type_metrics:QueryMetricsResponse": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/type_metrics:MetricBucket" } }, "description": "Metrics grouped by event type.", "title": "QueryMetricsResponse" }, "type_metrics:UsageType": { "type": "string", "enum": [ "storage_bytes", "message_count", "thread_count", "inbox_count", "pod_count", "domain_count" ], "description": "Type of usage metric. Inbox-scoped queries carry `storage_bytes`,\n`message_count`, and `thread_count`; pod-scoped queries add `inbox_count`\nand `domain_count`; organization-scoped queries add `pod_count`.", "title": "UsageType" }, "type_metrics:UsageTypes": { "type": "array", "items": { "$ref": "#/components/schemas/type_metrics:UsageType" }, "description": "List of usage metric types to query. Omit to query every type valid for the scope.", "title": "UsageTypes" }, "type_metrics:UsagePoint": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the point." }, "value": { "type": "integer", "format": "int64", "description": "Cumulative value of the usage metric at the timestamp." } }, "required": [ "timestamp", "value" ], "title": "UsagePoint" }, "type_metrics:QueryUsageResponse": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/type_metrics:UsagePoint" } }, "description": "Cumulative usage series grouped by usage type.", "title": "QueryUsageResponse" }, "type_inbox-events:InboxEventId": { "type": "string", "description": "ID of event.", "title": "InboxEventId" }, "type_inbox-events:InboxEventType": { "type": "string", "enum": [ "label.added", "label.removed" ], "description": "Type of inbox event. Wire format is dot.case to match the\nconvention used by webhook events (`message.received`,\n`domain.verified`, etc. in events.yml). Pre-2026-04 these were\n`label_added`/`label_removed` (snake_case). The Fern enum's `name`\nfield stays uppercase-snake (Fern convention); only the wire\n`value` changed.", "title": "InboxEventType" }, "type_inbox-events:InboxEvent": { "type": "object", "properties": { "organization_id": { "$ref": "#/components/schemas/type_:OrganizationId" }, "pod_id": { "type": "string", "description": "ID of pod." }, "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "event_id": { "$ref": "#/components/schemas/type_inbox-events:InboxEventId" }, "event_type": { "$ref": "#/components/schemas/type_inbox-events:InboxEventType" }, "message_id": { "type": "string", "description": "ID of message." }, "label": { "type": "string", "description": "Label added or removed." }, "event_at": { "type": "string", "format": "date-time", "description": "Time at which the event occurred." }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which the event was recorded." } }, "required": [ "organization_id", "pod_id", "inbox_id", "event_id", "event_type", "message_id", "label", "event_at", "created_at" ], "title": "InboxEvent" }, "type_inbox-events:ListInboxEventsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/type_inbox-events:InboxEvent" }, "description": "Ordered by `event_id` descending." } }, "required": [ "count", "events" ], "title": "ListInboxEventsResponse" }, "type_api-keys:ApiKeyId": { "type": "string", "description": "ID of api key.", "title": "ApiKeyId" }, "type_api-keys:Prefix": { "type": "string", "description": "Prefix of api key.", "title": "Prefix" }, "type_api-keys:Name": { "type": "string", "description": "Name of api key.", "title": "Name" }, "type_api-keys:ApiKeyPermissions": { "type": "object", "properties": { "inbox_read": { "type": "boolean", "description": "Read inbox details." }, "inbox_create": { "type": "boolean", "description": "Create new inboxes." }, "inbox_update": { "type": "boolean", "description": "Update inbox settings." }, "inbox_delete": { "type": "boolean", "description": "Delete inboxes." }, "message_read": { "type": "boolean", "description": "Read messages. Also required to read threads." }, "message_send": { "type": "boolean", "description": "Send messages." }, "message_update": { "type": "boolean", "description": "Update message labels. Also required to update threads." }, "message_delete": { "type": "boolean", "description": "Delete messages. Also required to delete threads." }, "label_spam_read": { "type": "boolean", "description": "Access messages labeled spam." }, "label_blocked_read": { "type": "boolean", "description": "Access messages labeled blocked." }, "label_unauthenticated_read": { "type": "boolean", "description": "Access messages labeled unauthenticated." }, "label_trash_read": { "type": "boolean", "description": "Access messages labeled trash." }, "draft_read": { "type": "boolean", "description": "Read drafts." }, "draft_create": { "type": "boolean", "description": "Create drafts." }, "draft_update": { "type": "boolean", "description": "Update drafts." }, "draft_delete": { "type": "boolean", "description": "Delete drafts." }, "draft_send": { "type": "boolean", "description": "Send drafts." }, "webhook_read": { "type": "boolean", "description": "Read webhook configurations." }, "webhook_create": { "type": "boolean", "description": "Create webhooks." }, "webhook_update": { "type": "boolean", "description": "Update webhooks." }, "webhook_delete": { "type": "boolean", "description": "Delete webhooks." }, "domain_read": { "type": "boolean", "description": "Read domain details." }, "domain_create": { "type": "boolean", "description": "Create domains." }, "domain_update": { "type": "boolean", "description": "Update domains." }, "domain_delete": { "type": "boolean", "description": "Delete domains." }, "list_entry_read": { "type": "boolean", "description": "Read list entries." }, "list_entry_create": { "type": "boolean", "description": "Create list entries." }, "list_entry_delete": { "type": "boolean", "description": "Delete list entries." }, "metrics_read": { "type": "boolean", "description": "Read metrics." }, "api_key_read": { "type": "boolean", "description": "Read API keys." }, "api_key_create": { "type": "boolean", "description": "Create API keys." }, "api_key_update": { "type": "boolean", "description": "Update API keys." }, "api_key_delete": { "type": "boolean", "description": "Delete API keys." }, "pod_read": { "type": "boolean", "description": "Read pods." }, "pod_create": { "type": "boolean", "description": "Create pods." }, "pod_delete": { "type": "boolean", "description": "Delete pods." } }, "description": "Granular permissions for the API key. When ommitted all permissions are granted. Otherwise, only permissions set to true are granted.", "title": "ApiKeyPermissions" }, "type_api-keys:CreatedAt": { "type": "string", "format": "date-time", "description": "Time at which api key was created.", "title": "CreatedAt" }, "type_api-keys:ApiKey": { "type": "object", "properties": { "api_key_id": { "$ref": "#/components/schemas/type_api-keys:ApiKeyId" }, "prefix": { "$ref": "#/components/schemas/type_api-keys:Prefix" }, "name": { "$ref": "#/components/schemas/type_api-keys:Name" }, "pod_id": { "type": "string", "description": "Pod ID the api key is scoped to. If set, the key can only access resources within this pod." }, "inbox_id": { "type": "string", "description": "Inbox ID the api key is scoped to. If set, the key can only access resources within this inbox." }, "used_at": { "type": "string", "format": "date-time", "description": "Time at which api key was last used." }, "permissions": { "$ref": "#/components/schemas/type_api-keys:ApiKeyPermissions" }, "created_at": { "$ref": "#/components/schemas/type_api-keys:CreatedAt" } }, "required": [ "api_key_id", "prefix", "name", "created_at" ], "title": "ApiKey" }, "type_api-keys:ListApiKeysResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/type_api-keys:ApiKey" }, "description": "Ordered by `created_at` descending." } }, "required": [ "count", "api_keys" ], "title": "ListApiKeysResponse" }, "type_api-keys:CreateApiKeyRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/type_api-keys:Name" }, "permissions": { "$ref": "#/components/schemas/type_api-keys:ApiKeyPermissions" } }, "title": "CreateApiKeyRequest" }, "type_api-keys:CreateApiKeyResponse": { "type": "object", "properties": { "api_key_id": { "$ref": "#/components/schemas/type_api-keys:ApiKeyId" }, "api_key": { "type": "string", "description": "API key." }, "prefix": { "$ref": "#/components/schemas/type_api-keys:Prefix" }, "name": { "$ref": "#/components/schemas/type_api-keys:Name" }, "pod_id": { "type": "string", "description": "Pod ID the api key is scoped to." }, "inbox_id": { "type": "string", "description": "Inbox ID the api key is scoped to." }, "permissions": { "$ref": "#/components/schemas/type_api-keys:ApiKeyPermissions" }, "created_at": { "$ref": "#/components/schemas/type_api-keys:CreatedAt" } }, "required": [ "api_key_id", "api_key", "prefix", "name", "created_at" ], "title": "CreateApiKeyResponse" }, "type_webhooks:CreateWebhookRequest": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/type_webhooks:Url" }, "event_types": { "$ref": "#/components/schemas/type_webhooks:CreateWebhookEventTypes" }, "client_id": { "$ref": "#/components/schemas/type_webhooks:ClientId" }, "headers": { "$ref": "#/components/schemas/type_webhooks:WebhookHeaders" }, "inbox_ids": { "$ref": "#/components/schemas/type_events:InboxIds" }, "pod_ids": { "$ref": "#/components/schemas/type_events:PodIds" } }, "required": [ "url", "event_types" ], "title": "CreateWebhookRequest" }, "type_webhooks:UpdateWebhookRequest": { "type": "object", "properties": { "event_types": { "$ref": "#/components/schemas/type_webhooks:UpdateWebhookEventTypes" }, "add_inbox_ids": { "$ref": "#/components/schemas/type_events:InboxIds", "description": "Inbox IDs to subscribe to the webhook." }, "remove_inbox_ids": { "$ref": "#/components/schemas/type_events:InboxIds", "description": "Inbox IDs to unsubscribe from the webhook." }, "add_pod_ids": { "$ref": "#/components/schemas/type_events:PodIds", "description": "Pod IDs to subscribe to the webhook." }, "remove_pod_ids": { "$ref": "#/components/schemas/type_events:PodIds", "description": "Pod IDs to unsubscribe from the webhook." } }, "title": "UpdateWebhookRequest" }, "type_domains:DomainId": { "type": "string", "description": "The ID of the domain.", "title": "DomainId" }, "type_domains:DomainName": { "type": "string", "description": "The name of the domain (e.g., `example.com`).", "title": "DomainName" }, "type_domains:FeedbackEnabled": { "type": "boolean", "description": "Bounce and complaint notifications are sent to your inboxes.", "title": "FeedbackEnabled" }, "type_domains:SubdomainsEnabled": { "type": "boolean", "description": "Allow inboxes on any subdomain of this domain. Adds a required wildcard MX\nrecord (`*.`) to `records`.", "title": "SubdomainsEnabled" }, "type_domains:TrackingEnabled": { "type": "boolean", "description": "Serve open tracking pixels from this domain. Adds a required `link.`\nCNAME record to `records`, which must be published and verified before\n`track_opens` can be used on a send.", "title": "TrackingEnabled" }, "type_domains:ClientId": { "type": "string", "description": "Client ID of domain.", "title": "ClientId" }, "type_domains:DomainItem": { "type": "object", "properties": { "pod_id": { "$ref": "#/components/schemas/type_pods:PodId" }, "domain_id": { "$ref": "#/components/schemas/type_domains:DomainId" }, "domain": { "$ref": "#/components/schemas/type_domains:DomainName" }, "feedback_enabled": { "$ref": "#/components/schemas/type_domains:FeedbackEnabled" }, "subdomains_enabled": { "$ref": "#/components/schemas/type_domains:SubdomainsEnabled" }, "tracking_enabled": { "$ref": "#/components/schemas/type_domains:TrackingEnabled" }, "client_id": { "$ref": "#/components/schemas/type_domains:ClientId" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time at which the domain was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which the domain was created." } }, "required": [ "domain_id", "domain", "feedback_enabled", "subdomains_enabled", "tracking_enabled", "updated_at", "created_at" ], "title": "DomainItem" }, "type_domains:ListDomainsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/type_domains:DomainItem" }, "description": "Ordered by `created_at` descending." } }, "required": [ "count", "domains" ], "title": "ListDomainsResponse" }, "type_domains:VerificationStatus": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "INVALID", "FAILED", "VERIFYING", "VERIFIED" ], "title": "VerificationStatus" }, "type_domains:Status": { "$ref": "#/components/schemas/type_domains:VerificationStatus", "description": "The verification status of the domain.", "title": "Status" }, "type_domains:RecordType": { "type": "string", "enum": [ "TXT", "CNAME", "MX" ], "title": "RecordType" }, "type_domains:RecordStatus": { "type": "string", "enum": [ "MISSING", "INVALID", "VALID" ], "title": "RecordStatus" }, "type_domains:VerificationRecord": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/type_domains:RecordType", "description": "The type of the DNS record." }, "name": { "type": "string", "description": "The name or host of the record." }, "value": { "type": "string", "description": "The value of the record." }, "status": { "$ref": "#/components/schemas/type_domains:RecordStatus", "description": "The verification status of this specific record." }, "priority": { "type": "integer", "description": "The priority of the MX record." }, "reason": { "type": "string", "description": "Why the record is INVALID, when known. `duplicate_records` means the expected value is present but extra records coexist at the same name; `value_mismatch` means a record exists but does not match the expected value." } }, "required": [ "type", "name", "value", "status" ], "title": "VerificationRecord" }, "type_domains:Domain": { "type": "object", "properties": { "pod_id": { "$ref": "#/components/schemas/type_pods:PodId" }, "domain_id": { "$ref": "#/components/schemas/type_domains:DomainId" }, "domain": { "$ref": "#/components/schemas/type_domains:DomainName" }, "status": { "$ref": "#/components/schemas/type_domains:Status" }, "reason": { "type": "string", "description": "Why the domain is not (yet) VERIFIED, when known. `dns_records_missing` / `dns_records_invalid` point at the DNS records. The `ses_*` values mean the records look right and sending-infrastructure validation has not converged: `ses_dkim_pending` / `ses_mail_from_pending` (still checking), `ses_dkim_temporary_failure` / `ses_mail_from_temporary_failure` (a transient error the infrastructure keeps retrying on its own — usually resolves without changes), `ses_dkim_failed` / `ses_mail_from_failed` (a terminal verdict; re-verify after fixing), `ses_dkim_not_started` / `ses_mail_from_not_started` (the attribute was never configured on the identity — re-verify to push it), and `ses_not_verified_for_sending`. Absent when VERIFIED." }, "feedback_enabled": { "$ref": "#/components/schemas/type_domains:FeedbackEnabled" }, "subdomains_enabled": { "$ref": "#/components/schemas/type_domains:SubdomainsEnabled" }, "tracking_enabled": { "$ref": "#/components/schemas/type_domains:TrackingEnabled" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/type_domains:VerificationRecord" }, "description": "A list of DNS records required to verify the domain. Includes a\nwildcard MX record (`*.`) when `subdomains_enabled` is true." }, "client_id": { "$ref": "#/components/schemas/type_domains:ClientId" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time at which the domain was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which the domain was created." } }, "required": [ "domain_id", "domain", "status", "feedback_enabled", "subdomains_enabled", "tracking_enabled", "records", "updated_at", "created_at" ], "title": "Domain" }, "type_domains:CreateDomainRequest": { "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/type_domains:DomainName" }, "feedback_enabled": { "$ref": "#/components/schemas/type_domains:FeedbackEnabled" }, "subdomains_enabled": { "$ref": "#/components/schemas/type_domains:SubdomainsEnabled" }, "tracking_enabled": { "$ref": "#/components/schemas/type_domains:TrackingEnabled" } }, "required": [ "domain" ], "title": "CreateDomainRequest" }, "type_domains:UpdateDomainRequest": { "type": "object", "properties": { "feedback_enabled": { "$ref": "#/components/schemas/type_domains:FeedbackEnabled" }, "subdomains_enabled": { "$ref": "#/components/schemas/type_domains:SubdomainsEnabled" }, "tracking_enabled": { "$ref": "#/components/schemas/type_domains:TrackingEnabled" } }, "description": "Provide at least one of `feedback_enabled`, `subdomains_enabled`, or\n`tracking_enabled`. Omitted\nfields are left unchanged; an empty body is rejected. Enabling\n`subdomains_enabled` on a verified domain returns it to `PENDING` until the\nnewly-required wildcard MX record (`*.`) is published and verified.", "title": "UpdateDomainRequest" }, "type_domains:GetSetupLinkResponse": { "type": "object", "properties": { "supported": { "type": "boolean", "description": "Whether one-click setup is available for this domain. `false` means the domain's DNS provider does not support Domain Connect (or does not carry the AgentMail template yet) — add the domain's `records` manually instead." }, "provider_name": { "type": "string", "description": "Display name of the domain's DNS provider, for the setup button label." }, "url": { "type": "string", "description": "The signed Domain Connect apply URL. Open it in a browser: the domain owner signs in at their DNS provider, reviews the records, and approves — the provider writes them." }, "width": { "type": "integer", "description": "Suggested popup width from the provider, in pixels." }, "height": { "type": "integer", "description": "Suggested popup height from the provider, in pixels." }, "state": { "type": "string", "description": "Opaque value echoed back on the provider's redirect. Store it before opening the URL and compare on return to tie the redirect to this request." }, "conflicting_provider": { "type": "string", "description": "Set when the domain currently has another email provider's MX records (for example Google Workspace). Applying the template would replace them — warn before proceeding." } }, "required": [ "supported" ], "title": "GetSetupLinkResponse" }, "type_lists:ListEntry": { "type": "object", "properties": { "entry": { "type": "string", "description": "Email address or domain of list entry." }, "organization_id": { "$ref": "#/components/schemas/type_:OrganizationId" }, "reason": { "type": "string", "description": "Reason for adding the entry." }, "direction": { "$ref": "#/components/schemas/type_lists:Direction" }, "list_type": { "$ref": "#/components/schemas/type_lists:ListType" }, "entry_type": { "$ref": "#/components/schemas/type_lists:EntryType" }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which entry was created." }, "read_only": { "type": "boolean", "description": "Whether the entry is read-only and cannot be deleted via the API." } }, "required": [ "entry", "organization_id", "direction", "list_type", "entry_type", "created_at" ], "title": "ListEntry" }, "type_lists:ListListEntriesResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/type_lists:ListEntry" }, "description": "Ordered by entry ascending." } }, "required": [ "count", "entries" ], "title": "ListListEntriesResponse" }, "type_api-keys:PublicJwkCoordinate": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "minLength": 43, "maxLength": 43, "description": "A 32-byte P-256 coordinate encoded as unpadded base64url.", "title": "PublicJwkCoordinate" }, "type_api-keys:PublicJwk": { "type": "object", "properties": { "kty": { "type": "string", "enum": [ "EC" ] }, "crv": { "type": "string", "enum": [ "P-256" ] }, "x": { "$ref": "#/components/schemas/type_api-keys:PublicJwkCoordinate" }, "y": { "$ref": "#/components/schemas/type_api-keys:PublicJwkCoordinate" } }, "required": [ "kty", "crv", "x", "y" ], "description": "A public P-256 JWK. The object accepts exactly `kty`, `crv`, `x`, and `y`.\nPrivate key material such as `d`, embedded key IDs, and all other members\nare rejected. The server also rejects coordinates that are not a point on\nP-256.", "title": "PublicJwk" }, "type_api-keys:PublicKeyMaterial": { "type": "object", "properties": { "jwk": { "$ref": "#/components/schemas/type_api-keys:PublicJwk" }, "fingerprint": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "minLength": 43, "maxLength": 43, "description": "RFC 7638 SHA-256 JWK thumbprint encoded as unpadded base64url." } }, "required": [ "jwk", "fingerprint" ], "description": "Registered public key material and its server-computed RFC 7638 thumbprint.", "title": "PublicKeyMaterial" }, "type_api-keys:PublicKeyScope": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ], "description": "Discriminator value: organization" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pod" ], "description": "Discriminator value: pod" }, "id": { "type": "string", "format": "uuid", "description": "ID of the pod." } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inbox" ], "description": "Discriminator value: inbox" }, "id": { "type": "string", "format": "email", "maxLength": 254, "description": "ID of the inbox." } }, "required": [ "type", "id" ] } ], "discriminator": { "propertyName": "type" }, "description": "The immutable scope in which a public-key credential can approve AgentID sign-in.", "title": "PublicKeyScope" }, "type_api-keys:PublicKeyCredential": { "type": "object", "properties": { "api_key_id": { "type": "string", "format": "uuid", "description": "Server-generated credential ID. Store this value as the signing key's `kid`." }, "type": { "type": "string", "enum": [ "public_key" ], "description": "Server-owned credential discriminator. Callers cannot select or update it." }, "name": { "$ref": "#/components/schemas/type_api-keys:Name", "description": "Human-readable credential name." }, "public_key": { "$ref": "#/components/schemas/type_api-keys:PublicKeyMaterial" }, "scope": { "$ref": "#/components/schemas/type_api-keys:PublicKeyScope" }, "expires_at": { "type": "string", "format": "date-time", "description": "Immutable absolute expiry. Omitted when the credential does not expire." }, "revoked_at": { "type": "string", "format": "date-time", "description": "Present when organization-wide revoke-all invalidated this credential generation." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "api_key_id", "type", "name", "public_key", "scope", "created_at", "updated_at" ], "description": "An AgentID sign-in credential. `type` and `api_key_id` are server-owned;\nuse `api_key_id` as the JWS `kid`. This response never contains a bearer\nsecret or private key.", "title": "PublicKeyCredential" }, "type_api-keys:ListPublicKeysResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "public_keys": { "type": "array", "items": { "$ref": "#/components/schemas/type_api-keys:PublicKeyCredential" }, "description": "Public-key credentials only, ordered by creation time descending by default." } }, "required": [ "count", "public_keys" ], "title": "ListPublicKeysResponse" }, "type_api-keys:CreatePublicKeyRequest": { "type": "object", "properties": { "public_key": { "$ref": "#/components/schemas/type_api-keys:PublicJwk" }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Defaults to `AgentID key {first eight fingerprint characters}`." }, "scope": { "$ref": "#/components/schemas/type_api-keys:PublicKeyScope", "description": "Omit to inherit the registering bearer key's exact scope. An explicit\nscope must be the caller's scope or a live descendant." }, "expires_at": { "type": "string", "format": "date-time", "description": "Future absolute expiry. Omit to inherit the registering bearer key's\nexpiry. A child credential cannot outlive its creator." } }, "required": [ "public_key" ], "description": "Register only a public P-256 JWK. Credential type, `api_key_id`, sign-in\neligibility, permissions, and generation are server-owned and are not\nrequest properties.", "title": "CreatePublicKeyRequest" }, "type_api-keys:UpdatePublicKeyNameRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "name" ], "description": "Rename a public-key credential. Key material, ID, type, scope, sign-in\neligibility, permissions, generation, and expiry are immutable.", "title": "UpdatePublicKeyNameRequest" }, "type_api-keys:RevokeAllAgentIdSignInKeysResponse": { "type": "object", "properties": { "previous_generation": { "type": "integer", "minimum": 0 }, "current_generation": { "type": "integer", "minimum": 1 }, "revoked_at": { "type": "string", "format": "date-time" } }, "required": [ "previous_generation", "current_generation", "revoked_at" ], "description": "Permanent idempotency receipt for an organization-wide AgentID sign-in key revocation.", "title": "RevokeAllAgentIdSignInKeysResponse" }, "type_api-keys:BrowserAuthorizationListLimit": { "type": "integer", "minimum": 1, "maximum": 100, "title": "BrowserAuthorizationListLimit" }, "type_api-keys:BrowserCredentialCreator": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bearer_api_key" ] }, "api_key_id": { "type": "string", "format": "uuid", "description": "Bearer API key that authorized creation of the browser credential." }, "created_at": { "type": "string", "format": "date-time", "description": "Incarnation timestamp of the authorizing bearer API key." } }, "required": [ "kind", "api_key_id", "created_at" ], "title": "BrowserCredentialCreator" }, "type_api-keys:BrowserCredential": { "type": "object", "properties": { "credential_id": { "type": "string", "format": "uuid" }, "public_key_fingerprint_prefix": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8}$", "minLength": 8, "maxLength": 8 }, "organization_id": { "type": "string", "format": "uuid" }, "pod_id": { "type": "string", "format": "uuid" }, "inbox_id": { "type": "string", "format": "email", "maxLength": 254 }, "created_by": { "$ref": "#/components/schemas/type_api-keys:BrowserCredentialCreator" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "credential_id", "public_key_fingerprint_prefix", "organization_id", "pod_id", "inbox_id", "created_by", "created_at", "expires_at" ], "description": "Owner-facing metadata for an active browser credential. Private key material never leaves the browser.", "title": "BrowserCredential" }, "type_api-keys:ListBrowserCredentialsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_api-keys:BrowserAuthorizationListLimit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/type_api-keys:BrowserCredential" } } }, "required": [ "count", "limit", "credentials" ], "title": "ListBrowserCredentialsResponse" }, "type_api-keys:BrowserEnrollmentLifecycleEventType": { "type": "string", "enum": [ "browser_enrollment_intent_created", "browser_credential_activated", "browser_enrollment_cancelled", "browser_credential_deleted" ], "title": "BrowserEnrollmentLifecycleEventType" }, "type_api-keys:BrowserLifecycleActor": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_key" ], "description": "Discriminator value: api_key" }, "api_key_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "api_key_id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "browser_credential" ], "description": "Discriminator value: browser_credential" }, "credential_id": { "type": "string", "format": "uuid" }, "authorizing_api_key_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "credential_id", "authorizing_api_key_id" ] } ], "discriminator": { "propertyName": "type" }, "title": "BrowserLifecycleActor" }, "type_api-keys:BrowserEnrollmentLifecycleEvent": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/type_api-keys:BrowserEnrollmentLifecycleEventType" }, "trace_id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "occurred_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "pod_id": { "type": "string", "format": "uuid" }, "actor": { "$ref": "#/components/schemas/type_api-keys:BrowserLifecycleActor" }, "enrollment_id": { "type": "string", "format": "uuid" }, "credential_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "trace_id", "event_id", "occurred_at", "organization_id", "pod_id", "actor", "enrollment_id", "credential_id" ], "title": "BrowserEnrollmentLifecycleEvent" }, "type_api-keys:BrowserConsentLifecycleEventType": { "type": "string", "enum": [ "browser_consent_created", "browser_consent_updated", "browser_consent_reused", "browser_consent_revoked" ], "title": "BrowserConsentLifecycleEventType" }, "type_api-keys:BrowserConsentLifecycleEvent": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/type_api-keys:BrowserConsentLifecycleEventType" }, "trace_id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "occurred_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "pod_id": { "type": "string", "format": "uuid" }, "actor": { "$ref": "#/components/schemas/type_api-keys:BrowserLifecycleActor" }, "consent_id": { "type": "string", "pattern": "^brc1_[A-Za-z0-9_-]{43}$", "minLength": 48, "maxLength": 48 }, "client_type": { "type": "string", "enum": [ "closed" ] }, "client_id": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "type", "trace_id", "event_id", "occurred_at", "organization_id", "pod_id", "actor", "consent_id", "client_type", "client_id" ], "title": "BrowserConsentLifecycleEvent" }, "type_api-keys:BrowserLifecycleEvent": { "oneOf": [ { "$ref": "#/components/schemas/type_api-keys:BrowserEnrollmentLifecycleEvent" }, { "$ref": "#/components/schemas/type_api-keys:BrowserConsentLifecycleEvent" } ], "title": "BrowserLifecycleEvent" }, "type_api-keys:ListBrowserLifecycleEventsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_api-keys:BrowserAuthorizationListLimit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/type_api-keys:BrowserLifecycleEvent" } } }, "required": [ "count", "limit", "events" ], "title": "ListBrowserLifecycleEventsResponse" }, "type_api-keys:BrowserConsent": { "type": "object", "properties": { "consent_id": { "type": "string", "pattern": "^brc1_[A-Za-z0-9_-]{43}$", "minLength": 48, "maxLength": 48 }, "inbox_id": { "type": "string", "format": "email", "maxLength": 254 }, "client_type": { "type": "string", "enum": [ "closed" ] }, "client_id": { "type": "string", "minLength": 1, "maxLength": 2048 }, "client_url": { "type": "string", "description": "Registered client URL, when one is available." }, "approved_scopes": { "type": "array", "items": { "type": "string" }, "description": "At least one non-empty scope approved for this client." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "consent_id", "inbox_id", "client_type", "client_id", "approved_scopes", "created_at", "updated_at", "expires_at" ], "description": "Remembered approval for one closed AgentID client and inbox.", "title": "BrowserConsent" }, "type_api-keys:ListBrowserConsentsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_api-keys:BrowserAuthorizationListLimit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "consents": { "type": "array", "items": { "$ref": "#/components/schemas/type_api-keys:BrowserConsent" } } }, "required": [ "count", "limit", "consents" ], "title": "ListBrowserConsentsResponse" }, "type_accounts:ProviderId": { "type": "string", "format": "uuid", "description": "ID of provider.", "title": "ProviderId" }, "type_providers:Provider": { "type": "object", "properties": { "provider_id": { "$ref": "#/components/schemas/type_accounts:ProviderId" }, "name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time at which provider was last updated." }, "description": { "type": "string" }, "logo_url": { "type": "string" }, "terms_url": { "type": "string" }, "privacy_url": { "type": "string" } }, "required": [ "provider_id" ], "description": "A provider an inbox can sign in to.", "title": "Provider" }, "type_providers:ListProvidersResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/type_providers:Provider" } } }, "required": [ "count", "limit", "providers" ], "title": "ListProvidersResponse" }, "type_providers:SearchProvidersResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/type_providers:Provider" } } }, "required": [ "count", "limit", "providers" ], "title": "SearchProvidersResponse" }, "type_accounts:AccountId": { "type": "string", "format": "uuid", "description": "ID of account.", "title": "AccountId" }, "type_accounts:Account": { "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/type_accounts:AccountId" }, "provider_id": { "$ref": "#/components/schemas/type_accounts:ProviderId" }, "provider_name": { "type": "string", "description": "Display name of provider." }, "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "pod_id": { "$ref": "#/components/schemas/type_pods:PodId" }, "organization_id": { "$ref": "#/components/schemas/type_:OrganizationId" }, "first_signed_in_at": { "type": "string", "format": "date-time", "description": "Time of first sign-in at provider." }, "last_signed_in_at": { "type": "string", "format": "date-time", "description": "Time of most recent sign-in at provider." }, "sign_in_count": { "type": "integer", "description": "Number of sign-ins at provider." } }, "required": [ "account_id", "provider_id", "inbox_id", "pod_id", "organization_id", "first_signed_in_at", "last_signed_in_at", "sign_in_count" ], "description": "One inbox signed in at one provider.", "title": "Account" }, "type_providers:ListProviderAccountsResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/type_providers:Provider" }, "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/type_accounts:Account" } } }, "required": [ "count", "limit", "accounts" ], "title": "ListProviderAccountsResponse" }, "type_providers:ConnectProviderBody": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId", "description": "Inbox to connect. Required unless the API key is scoped to an inbox." }, "authorize": { "type": "boolean", "description": "Authorize the provider for this inbox, skipping the first-use disclosure page." } }, "title": "ConnectProviderBody" }, "type_providers:ConnectProviderAccepted": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID of session." }, "magic_url": { "type": "string", "description": "Single-use URL to open in the browser that will hold the sign-in." }, "expires_at": { "type": "string", "format": "date-time", "description": "Time at which the URL expires." } }, "required": [ "session_id", "magic_url", "expires_at" ], "title": "ConnectProviderAccepted" }, "type_accounts:ListAccountsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/type_accounts:Account" } } }, "required": [ "count", "limit", "accounts" ], "title": "ListAccountsResponse" }, "type_pods:Name": { "type": "string", "description": "Name of pod.", "title": "Name" }, "type_pods:ClientId": { "type": "string", "description": "Client ID of pod.", "title": "ClientId" }, "type_pods:Pod": { "type": "object", "properties": { "pod_id": { "$ref": "#/components/schemas/type_pods:PodId" }, "name": { "$ref": "#/components/schemas/type_pods:Name" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time at which pod was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which pod was created." }, "client_id": { "$ref": "#/components/schemas/type_pods:ClientId" } }, "required": [ "pod_id", "name", "updated_at", "created_at" ], "title": "Pod" }, "type_pods:ListPodsResponse": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/type_:Count" }, "limit": { "$ref": "#/components/schemas/type_:Limit" }, "next_page_token": { "$ref": "#/components/schemas/type_:PageToken" }, "pods": { "type": "array", "items": { "$ref": "#/components/schemas/type_pods:Pod" }, "description": "Ordered by `created_at` descending." } }, "required": [ "count", "pods" ], "title": "ListPodsResponse" }, "type_pods:CreatePodRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/type_pods:Name" }, "client_id": { "$ref": "#/components/schemas/type_pods:ClientId" } }, "title": "CreatePodRequest" }, "type_webhooks:CreatePodWebhookRequest": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/type_webhooks:Url" }, "event_types": { "$ref": "#/components/schemas/type_webhooks:CreateWebhookEventTypes" }, "client_id": { "$ref": "#/components/schemas/type_webhooks:ClientId" }, "headers": { "$ref": "#/components/schemas/type_webhooks:WebhookHeaders" }, "inbox_ids": { "$ref": "#/components/schemas/type_events:InboxIds" } }, "required": [ "url", "event_types" ], "description": "Create a webhook scoped to a pod. The pod comes from the path, so `pod_ids` is not accepted.\nOptionally pass `inbox_ids` to narrow the webhook to specific inboxes within the pod; omit to\nreceive events for the whole pod.", "title": "CreatePodWebhookRequest" }, "type_webhooks:UpdatePodWebhookRequest": { "type": "object", "properties": { "event_types": { "$ref": "#/components/schemas/type_webhooks:UpdateWebhookEventTypes" }, "add_inbox_ids": { "$ref": "#/components/schemas/type_events:InboxIds", "description": "Inbox IDs to subscribe to the webhook." }, "remove_inbox_ids": { "$ref": "#/components/schemas/type_events:InboxIds", "description": "Inbox IDs to unsubscribe from the webhook." } }, "description": "Update a pod-scoped webhook. You can adjust which inboxes within the pod it listens to and replace\nits `event_types`, but not the pod scope itself.", "title": "UpdatePodWebhookRequest" }, "type_organizations:Organization": { "type": "object", "properties": { "organization_id": { "$ref": "#/components/schemas/type_:OrganizationId" }, "inbox_count": { "type": "integer", "description": "Current number of inboxes." }, "domain_count": { "type": "integer", "description": "Current number of domains." }, "inbox_limit": { "type": "integer", "description": "Maximum number of inboxes allowed." }, "domain_limit": { "type": "integer", "description": "Maximum number of domains allowed." }, "billing_id": { "type": "string", "description": "Provider-agnostic billing customer ID." }, "billing_type": { "type": "string", "description": "Billing provider type (e.g. \"stripe\")." }, "billing_subscription_id": { "type": "string", "description": "Active billing subscription ID." }, "authentication_id": { "type": "string", "description": "Provider-agnostic authentication ID." }, "authentication_type": { "type": "string", "description": "Authentication provider type." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time at which organization was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "Time at which organization was created." } }, "required": [ "organization_id", "inbox_count", "domain_count", "updated_at", "created_at" ], "description": "Organization details with usage limits and counts.", "title": "Organization" }, "type_auth:ScopeType": { "type": "string", "enum": [ "organization", "pod", "inbox" ], "description": "The scope tier the authenticated credential is bound to.", "title": "ScopeType" }, "type_auth:Identity": { "type": "object", "properties": { "scope_type": { "$ref": "#/components/schemas/type_auth:ScopeType" }, "scope_id": { "type": "string", "description": "ID of the most specific scope the credential is bound to.\nEquals inbox_id when scope_type is inbox, pod_id when pod, organization_id when organization." }, "organization_id": { "$ref": "#/components/schemas/type_:OrganizationId" }, "pod_id": { "type": "string", "description": "ID of the pod the credential is scoped to. Present when scope_type is pod or inbox." }, "inbox_id": { "type": "string", "description": "ID of the inbox the credential is scoped to. Present when scope_type is inbox." }, "api_key_id": { "type": "string", "description": "ID of the API key used to authenticate. Absent for JWT and proxy credentials." } }, "required": [ "scope_type", "scope_id", "organization_id" ], "description": "Identity and scope of the authenticated credential.", "title": "Identity" }, "type_webhooks/events:SvixId": { "type": "string", "description": "ID of webhook message.", "title": "SvixId" }, "type_webhooks/events:SvixSignature": { "type": "string", "description": "Signature of webhook message.", "title": "SvixSignature" }, "type_webhooks/events:SvixTimestamp": { "type": "string", "format": "date-time", "description": "Timestamp of webhook message.", "title": "SvixTimestamp" }, "type_events:MessageReceivedEventType": { "type": "string", "enum": [ "message.received", "message.received.spam", "message.received.blocked", "message.received.unauthenticated" ], "title": "MessageReceivedEventType" }, "type_events:EventId": { "type": "string", "description": "ID of event.", "title": "EventId" }, "type_events:MessageReceivedEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event_type": { "$ref": "#/components/schemas/type_events:MessageReceivedEventType" }, "event_id": { "$ref": "#/components/schemas/type_events:EventId" }, "message": { "$ref": "#/components/schemas/type_messages:Message" }, "thread": { "$ref": "#/components/schemas/type_threads:ThreadItem" } }, "required": [ "type", "event_type", "event_id", "message", "thread" ], "description": "A message was received. Spam, blocked, and unauthenticated received-message events use the same payload shape with different `event_type` values.", "title": "MessageReceivedEvent" }, "type_events:Timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of event.", "title": "Timestamp" }, "type_events:Send": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "timestamp": { "$ref": "#/components/schemas/type_events:Timestamp" }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "Sent recipients." } }, "required": [ "inbox_id", "thread_id", "message_id", "timestamp", "recipients" ], "title": "Send" }, "type_events:MessageSentEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event_type": { "type": "string", "enum": [ "message.sent" ] }, "event_id": { "$ref": "#/components/schemas/type_events:EventId" }, "send": { "$ref": "#/components/schemas/type_events:Send" } }, "required": [ "type", "event_type", "event_id", "send" ], "title": "MessageSentEvent" }, "type_events:Delivery": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "timestamp": { "$ref": "#/components/schemas/type_events:Timestamp" }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "Delivered recipients." } }, "required": [ "inbox_id", "thread_id", "message_id", "timestamp", "recipients" ], "title": "Delivery" }, "type_events:MessageDeliveredEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event_type": { "type": "string", "enum": [ "message.delivered" ] }, "event_id": { "$ref": "#/components/schemas/type_events:EventId" }, "delivery": { "$ref": "#/components/schemas/type_events:Delivery" } }, "required": [ "type", "event_type", "event_id", "delivery" ], "title": "MessageDeliveredEvent" }, "type_events:Recipient": { "type": "object", "properties": { "address": { "type": "string", "description": "Recipient address." }, "status": { "type": "string", "description": "Recipient status." } }, "required": [ "address", "status" ], "title": "Recipient" }, "type_events:Bounce": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "timestamp": { "$ref": "#/components/schemas/type_events:Timestamp" }, "type": { "type": "string", "description": "Bounce type." }, "sub_type": { "type": "string", "description": "Bounce sub-type." }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/type_events:Recipient" }, "description": "Bounced recipients." } }, "required": [ "inbox_id", "thread_id", "message_id", "timestamp", "type", "sub_type", "recipients" ], "title": "Bounce" }, "type_events:MessageBouncedEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event_type": { "type": "string", "enum": [ "message.bounced" ] }, "event_id": { "$ref": "#/components/schemas/type_events:EventId" }, "bounce": { "$ref": "#/components/schemas/type_events:Bounce" } }, "required": [ "type", "event_type", "event_id", "bounce" ], "title": "MessageBouncedEvent" }, "type_events:Complaint": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "timestamp": { "$ref": "#/components/schemas/type_events:Timestamp" }, "type": { "type": "string", "description": "Complaint type." }, "sub_type": { "type": "string", "description": "Complaint sub-type." }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "Complained recipients." } }, "required": [ "inbox_id", "thread_id", "message_id", "timestamp", "type", "sub_type", "recipients" ], "title": "Complaint" }, "type_events:MessageComplainedEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event_type": { "type": "string", "enum": [ "message.complained" ] }, "event_id": { "$ref": "#/components/schemas/type_events:EventId" }, "complaint": { "$ref": "#/components/schemas/type_events:Complaint" } }, "required": [ "type", "event_type", "event_id", "complaint" ], "title": "MessageComplainedEvent" }, "type_events:Reject": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "timestamp": { "$ref": "#/components/schemas/type_events:Timestamp" }, "reason": { "type": "string", "description": "Reject reason." } }, "required": [ "inbox_id", "thread_id", "message_id", "timestamp", "reason" ], "title": "Reject" }, "type_events:MessageRejectedEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event_type": { "type": "string", "enum": [ "message.rejected" ] }, "event_id": { "$ref": "#/components/schemas/type_events:EventId" }, "reject": { "$ref": "#/components/schemas/type_events:Reject" } }, "required": [ "type", "event_type", "event_id", "reject" ], "title": "MessageRejectedEvent" }, "type_events:Open": { "type": "object", "properties": { "inbox_id": { "$ref": "#/components/schemas/type_inboxes:InboxId" }, "thread_id": { "$ref": "#/components/schemas/type_threads:ThreadId" }, "message_id": { "$ref": "#/components/schemas/type_messages:MessageId" }, "timestamp": { "$ref": "#/components/schemas/type_events:Timestamp" } }, "required": [ "inbox_id", "thread_id", "message_id", "timestamp" ], "title": "Open" }, "type_events:MessageOpenedEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event_type": { "type": "string", "enum": [ "message.opened" ] }, "event_id": { "$ref": "#/components/schemas/type_events:EventId" }, "open": { "$ref": "#/components/schemas/type_events:Open" } }, "required": [ "type", "event_type", "event_id", "open" ], "description": "A tracked message was opened for the first time. Sent once per message: repeat opens do not\nresend it.", "title": "MessageOpenedEvent" }, "type_events:DomainVerifiedEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event_type": { "type": "string", "enum": [ "domain.verified" ] }, "event_id": { "$ref": "#/components/schemas/type_events:EventId" }, "domain": { "$ref": "#/components/schemas/type_domains:Domain" } }, "required": [ "type", "event_type", "event_id", "domain" ], "title": "DomainVerifiedEvent" } }, "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer" } } } }