{"openapi":"3.1.0","info":{"title":"AgenticMailCenter Agent API","version":"v1","description":"Agent-only REST operations. The browser, administrative, mailbox lifecycle, and internal routes are intentionally excluded."},"servers":[{"url":"https://YOUR_AGENTICMAILCENTER_ORIGIN"}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"tenant API key","description":"Use a tenant-bound key created by an owner or administrator."}}},"paths":{"/v1/accounts":{"get":{"operationId":"get_accounts","summary":"GET /v1/accounts","tags":["Agent REST v1"],"parameters":[],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/accounts/{account_id}":{"get":{"operationId":"get_accounts_account_id","summary":"GET /v1/accounts/{account_id}","tags":["Agent REST v1"],"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/identities":{"get":{"operationId":"get_identities","summary":"GET /v1/identities","tags":["Agent REST v1"],"parameters":[],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/labels":{"get":{"operationId":"get_labels","summary":"GET /v1/labels","tags":["Agent REST v1"],"parameters":[],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/messages":{"get":{"operationId":"get_messages","summary":"GET /v1/messages","tags":["Agent REST v1"],"parameters":[],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/messages/{message_id}":{"get":{"operationId":"get_messages_message_id","summary":"GET /v1/messages/{message_id}","tags":["Agent REST v1"],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/messages/{message_id}/content":{"get":{"operationId":"get_messages_message_id_content","summary":"GET /v1/messages/{message_id}/content","tags":["Agent REST v1"],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/messages/{message_id}/enrichment":{"get":{"operationId":"get_messages_message_id_enrichment","summary":"GET /v1/messages/{message_id}/enrichment","tags":["Agent REST v1"],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/threads":{"get":{"operationId":"get_threads","summary":"GET /v1/threads","tags":["Agent REST v1"],"parameters":[{"name":"sort","in":"query","schema":{"type":"string","enum":["received_at","subject","sender_name","sender_email"],"default":"received_at"},"description":"Global conversation ordering. Received means provider mailbox arrival; unknown values sort last."},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque next_cursor from the previous page. Preserve the same tenant, account, filters, sort, direction and compact option."},{"name":"include_matched_message_ids","in":"query","schema":{"type":"boolean","default":true},"description":"False omits message-ID arrays while preserving matching counts and bounded representative metadata."}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/threads/{thread_id}":{"get":{"operationId":"get_threads_thread_id","summary":"GET /v1/threads/{thread_id}","tags":["Agent REST v1"],"parameters":[{"name":"thread_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/attachments/{attachment_id}":{"get":{"operationId":"get_attachments_attachment_id","summary":"GET /v1/attachments/{attachment_id}","tags":["Agent REST v1"],"parameters":[{"name":"attachment_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/drafts":{"get":{"operationId":"get_drafts","summary":"GET /v1/drafts","tags":["Agent REST v1"],"parameters":[],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}},"post":{"operationId":"post_drafts","summary":"POST /v1/drafts","tags":["Agent REST v1"],"parameters":[],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:write","responses":{"201":{"description":"Draft created."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}},"requestBody":{"required":true,"description":"Draft fields and recipients.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["account_id","agent_identity_id","idempotency_key","to_addresses","body_text"],"properties":{"account_id":{"type":"string","minLength":1,"maxLength":65536},"agent_identity_id":{"type":"string","minLength":1,"maxLength":65536},"idempotency_key":{"type":"string","minLength":1,"maxLength":65536},"subject":{"type":"string","maxLength":65536},"to_addresses":{"type":"array","description":"Primary recipients.","maxItems":256,"items":{"type":"object","additionalProperties":false,"required":["address"],"properties":{"address":{"type":"string","minLength":1,"maxLength":254},"name":{"type":"string","minLength":1,"maxLength":65536}}}},"cc_addresses":{"type":"array","description":"Carbon-copy recipients.","maxItems":256,"items":{"type":"object","additionalProperties":false,"required":["address"],"properties":{"address":{"type":"string","minLength":1,"maxLength":254},"name":{"type":"string","minLength":1,"maxLength":65536}}}},"bcc_addresses":{"type":"array","description":"Blind-carbon-copy recipients.","maxItems":256,"items":{"type":"object","additionalProperties":false,"required":["address"],"properties":{"address":{"type":"string","minLength":1,"maxLength":254},"name":{"type":"string","minLength":1,"maxLength":65536}}}},"attachments":{"type":"array","description":"Outbound attachment descriptors.","maxItems":64,"items":{"type":"object","additionalProperties":false,"properties":{"filename":{"type":"string","minLength":1,"maxLength":65536},"contentType":{"type":"string","minLength":1,"maxLength":65536},"content_type":{"type":"string","minLength":1,"maxLength":65536},"content":{"type":"string","maxLength":699052},"cid":{"type":"string","minLength":1,"maxLength":65536}}}},"body_text":{"type":"string","maxLength":65536},"body_html":{"type":"string","maxLength":65536},"thread_id":{"type":"string","minLength":1,"maxLength":65536},"reply_to_message_id":{"type":"string","minLength":1,"maxLength":65536}}}}}}}},"/v1/drafts/{draft_id}":{"get":{"operationId":"get_drafts_draft_id","summary":"GET /v1/drafts/{draft_id}","tags":["Agent REST v1"],"parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}},"patch":{"operationId":"patch_drafts_draft_id","summary":"PATCH /v1/drafts/{draft_id}","tags":["Agent REST v1"],"parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:write","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}},"requestBody":{"required":true,"description":"Draft fields to update.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"subject":{"type":"string","maxLength":65536},"to_addresses":{"type":"array","description":"Primary recipients.","maxItems":256,"items":{"type":"object","additionalProperties":false,"required":["address"],"properties":{"address":{"type":"string","minLength":1,"maxLength":254},"name":{"type":"string","minLength":1,"maxLength":65536}}}},"cc_addresses":{"type":"array","description":"Carbon-copy recipients.","maxItems":256,"items":{"type":"object","additionalProperties":false,"required":["address"],"properties":{"address":{"type":"string","minLength":1,"maxLength":254},"name":{"type":"string","minLength":1,"maxLength":65536}}}},"bcc_addresses":{"type":"array","description":"Blind-carbon-copy recipients.","maxItems":256,"items":{"type":"object","additionalProperties":false,"required":["address"],"properties":{"address":{"type":"string","minLength":1,"maxLength":254},"name":{"type":"string","minLength":1,"maxLength":65536}}}},"body_text":{"type":"string","maxLength":65536},"body_html":{"type":"string","maxLength":65536},"attachments":{"type":"array","description":"Outbound attachment descriptors.","maxItems":64,"items":{"type":"object","additionalProperties":false,"properties":{"filename":{"type":"string","minLength":1,"maxLength":65536},"contentType":{"type":"string","minLength":1,"maxLength":65536},"content_type":{"type":"string","minLength":1,"maxLength":65536},"content":{"type":"string","maxLength":699052},"cid":{"type":"string","minLength":1,"maxLength":65536}}}}}}}}}}},"/v1/events":{"get":{"operationId":"get_events","summary":"GET /v1/events","tags":["Agent REST v1"],"parameters":[],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:read","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/drafts/{draft_id}/submit":{"post":{"operationId":"post_drafts_draft_id_submit","summary":"POST /v1/drafts/{draft_id}/submit","tags":["Agent REST v1"],"parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:write","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/drafts/{draft_id}/send":{"post":{"operationId":"post_drafts_draft_id_send","summary":"POST /v1/drafts/{draft_id}/send","tags":["Agent REST v1"],"parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:send","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}}}},"/v1/messages/{message_id}/labels":{"post":{"operationId":"post_messages_message_id_labels","summary":"POST /v1/messages/{message_id}/labels","tags":["Agent REST v1"],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:write","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}},"requestBody":{"required":true,"description":"An existing label or fields for a new label.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"oneOf":[{"required":["label_id"]},{"required":["name"]}],"properties":{"label_id":{"type":"string","minLength":1,"maxLength":65536},"name":{"type":"string","minLength":1,"maxLength":65536},"color":{"type":"string","minLength":1,"maxLength":65536},"description":{"type":"string","maxLength":65536}}}}}}}},"/v1/messages/{message_id}/labels/remove":{"post":{"operationId":"post_messages_message_id_labels_remove","summary":"POST /v1/messages/{message_id}/labels/remove","tags":["Agent REST v1"],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"security":[{"bearerApiKey":[]}],"x-agent-scope":"gateway:write","responses":{"200":{"description":"Successful response."},"401":{"description":"Missing or invalid tenant-bound API key."},"403":{"description":"The key lacks the operation scope."}},"requestBody":{"required":true,"description":"The label id or name to remove.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"oneOf":[{"required":["label_id"]},{"required":["name"]}],"properties":{"label_id":{"type":"string","minLength":1,"maxLength":65536},"name":{"type":"string","minLength":1,"maxLength":65536}}}}}}}}}}