{"openapi":"3.0.3","info":{"title":"Scargo Mail API","version":"0.1.0","description":"Email identities for agents. Bearer account keys provision mailboxes; scoped agent keys send, read, and reply. Sending is asynchronous: 202 means durably queued, not delivered. Poll messages or events for outcomes."},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{}},"paths":{"/admin/accounts":{"post":{"summary":"Create an account (deployment administrator key required)","tags":["Administration"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/domains":{"get":{"summary":"List your custom email domains and DNS records","tags":["Domains"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Add a custom email domain and obtain its ownership TXT record","tags":["Domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":232}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/domains/{domainId}":{"get":{"summary":"Get saved domain verification status","tags":["Domains"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Disconnect a domain, pause its mailboxes, and retain message history","tags":["Domains"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/domains/{domainId}/verify":{"post":{"summary":"Check ownership and start or refresh asynchronous mail DNS verification","tags":["Domains"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/me":{"get":{"summary":"Inspect current identity and permissions","tags":["Identity"],"responses":{"200":{"description":"Default Response"}}}},"/v1/mailboxes":{"get":{"summary":"List accessible mailboxes","tags":["Mailboxes"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a mailbox and its first scoped agent key","tags":["Mailboxes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"domain_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"local_part":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,46}[a-z0-9]$"}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/mailboxes/{mailboxId}":{"patch":{"summary":"Pause or resume outbound sending","tags":["Mailboxes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]}},"required":["status"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"mailboxId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/keys":{"get":{"summary":"List API key metadata (secrets are never returned)","tags":["Keys"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create an account key or scoped mailbox key","tags":["Keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"mailbox_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"scopes":{"default":["read","send"],"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["read","send"]}}},"required":["name","scopes"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/keys/{keyId}":{"delete":{"summary":"Revoke a key","tags":["Keys"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"keyId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/mailboxes/{mailboxId}/messages":{"get":{"summary":"List messages, newest first","tags":["Messages"],"parameters":[{"schema":{"default":50,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":true},{"schema":{"type":"string","maxLength":500},"in":"query","name":"before","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"mailboxId","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Queue an email (202 does not mean delivered)","tags":["Messages"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","maxLength":254,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"subject":{"type":"string","minLength":1,"maxLength":998,"pattern":"^[^\\r\\n]*$"},"text":{"type":"string","minLength":1,"maxLength":262144},"html":{"type":"string","maxLength":262144}},"required":["to","subject","text"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"mailboxId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"header","name":"idempotency-key","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/mailboxes/{mailboxId}/messages/{messageId}":{"get":{"summary":"Read a message","tags":["Messages"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"mailboxId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"messageId","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Mark a message read or unread","tags":["Messages"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"read":{"type":"boolean"}},"required":["read"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"mailboxId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"messageId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/mailboxes/{mailboxId}/messages/{messageId}/reply":{"post":{"summary":"Reply to an inbound message with email threading headers","tags":["Messages"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":262144},"html":{"type":"string","maxLength":262144}},"required":["text"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"mailboxId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"messageId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"header","name":"idempotency-key","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/mailboxes/{mailboxId}/messages/{messageId}/attachments/{attachmentId}":{"get":{"summary":"Get a temporary download URL for a received attachment","tags":["Messages"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"mailboxId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"messageId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"attachmentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/events":{"get":{"summary":"Poll durable events after a cursor","tags":["Events"],"parameters":[{"schema":{"default":"0","type":"string","pattern":"^\\d{1,18}$"},"in":"query","name":"after","required":true},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"security":[{"bearerAuth":[]}]}