{"openapi":"3.1.0","info":{"title":"Agent Mail","version":"1.0.0","description":"Invite-only mail API for agents. Send a bearer key. The panel at /admin uses Cloudflare Access, not this key."},"servers":[{"url":"https://agents.theserverless.dev"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"SendResult":{"type":"object","properties":{"outcome":{"type":"string","enum":["sent","drafted"]},"messageId":{"type":"string"},"providerMessageId":{"type":"string","nullable":true},"threadId":{"type":"string","nullable":true},"draftId":{"type":"string","nullable":true},"status":{"type":"string"},"reason":{"type":"string"},"statusUrl":{"type":"string"},"adminUrl":{"type":"string","description":"Panel URL for this draft. Present when outcome is drafted."},"approveUrl":{"type":"string","nullable":true,"description":"One-time approval link. Present only on the create response that drafted the message. Null when approve links are off. Later GETs omit this field because the raw token is not stored."}}},"Draft":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","sent","rejected"]},"reason":{"type":"string"},"subject":{"type":"string"},"adminUrl":{"type":"string"},"statusUrl":{"type":"string"}}}}},"security":[{"bearer":[]}],"paths":{"/v1/me":{"get":{"summary":"Who this key is","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/inboxes":{"get":{"summary":"List inboxes for this agent","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/inboxes/{id}":{"get":{"summary":"Read one inbox","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/inboxes/{id}/threads":{"get":{"summary":"List threads","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/inboxes/{id}/threads/{threadId}":{"get":{"summary":"Read a thread and its messages","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/inboxes/{id}/messages":{"get":{"summary":"List messages after a cursor","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}},"parameters":[{"name":"since","in":"query","required":false,"description":"Return messages with seq greater than this value.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of messages.","schema":{"type":"integer"}}]}},"/v1/inboxes/{id}/messages/{messageId}":{"get":{"summary":"Read one message","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/inboxes/{id}/messages/{messageId}/raw":{"get":{"summary":"Download the raw .eml file","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/inboxes/{id}/messages/{messageId}/attachments/{index}":{"get":{"summary":"Download one attachment","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/inboxes/{id}/wait":{"get":{"summary":"Long-poll for new mail","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}},"parameters":[{"name":"since","in":"query","required":false,"description":"Cursor from the previous call.","schema":{"type":"integer"}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait. Maximum 25.","schema":{"type":"integer"}}]}},"/v1/inboxes/{id}/send":{"post":{"summary":"Send or draft a message. The policy chooses the outcome. A drafted response includes adminUrl. approveUrl is returned only on this response, and only when approve links are on.","responses":{"201":{"description":"Sent"},"202":{"description":"Drafted"},"403":{"$ref":"#/components/schemas/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","subject","text"],"properties":{"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"threadId":{"type":"string"},"inReplyTo":{"type":"string","description":"Internal message id or Message-ID header."}}}}}}}},"/v1/inboxes/{id}/threads/{threadId}/reply":{"post":{"summary":"Reply in a thread. Threading headers are set on send.","responses":{"201":{"description":"Sent"},"202":{"description":"Drafted"}}}},"/v1/drafts":{"get":{"summary":"List drafts for this agent. Each draft includes adminUrl and does not include approveUrl.","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/drafts/{id}":{"get":{"summary":"Read draft status. Includes adminUrl. Does not include approveUrl.","responses":{"200":{"description":"OK"},"401":{"description":"Missing or bad key"},"404":{"description":"Not in scope"}}}},"/v1/openapi.json":{"get":{"summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI document"}}}}}}