{"openapi":"3.1.0","info":{"title":"CIA Mail API","version":"1.0.0","description":"Send mail as your domain's mailboxes, and read/answer shared mailboxes (contact@…). Keys are created by your domain administrator, each limited to scopes (send, read), mailboxes, and an hourly quota."},"servers":[{"url":"https://api.cia-creative.com/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer ciam_…"}},"schemas":{"Address":{"oneOf":[{"type":"string","format":"email"},{"type":"object","required":["address"],"properties":{"name":{"type":"string"},"address":{"type":"string","format":"email"}}}]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Status":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","sending","sent","failed"]},"message_id":{"type":"string","description":"RFC 5322 Message-ID of the sent message"},"from":{"type":"string"},"recipients":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"attempts":{"type":"integer"},"last_error":{"type":["string","null"]},"smtp_response":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"}}},"Attachment":{"type":"object","required":["filename","content"],"properties":{"filename":{"type":"string"},"content":{"type":"string","format":"byte","description":"base64"},"content_type":{"type":"string"}}}}},"paths":{"/messages":{"post":{"summary":"Send a message","description":"Queues the message and answers 202 at once; the status then goes queued → sent (or failed). Temporary SMTP failures are retried with backoff for about 5 hours. Requires the send scope; `from` must be a mailbox granted to the key.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Same key twice → the first submission's answer (200), no second message."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","subject"],"properties":{"from":{"oneOf":[{"type":"string","format":"email"},{"type":"object","required":["address"],"properties":{"name":{"type":"string"},"address":{"type":"string","format":"email"}}}]},"to":{"type":"array","items":{"oneOf":[{"type":"string","format":"email"},{"type":"object","required":["address"],"properties":{"name":{"type":"string"},"address":{"type":"string","format":"email"}}}]}},"cc":{"type":"array","items":{"oneOf":[{"type":"string","format":"email"},{"type":"object","required":["address"],"properties":{"name":{"type":"string"},"address":{"type":"string","format":"email"}}}]}},"bcc":{"type":"array","items":{"oneOf":[{"type":"string","format":"email"},{"type":"object","required":["address"],"properties":{"name":{"type":"string"},"address":{"type":"string","format":"email"}}}]},"description":"In the envelope only, never in the headers"},"reply_to":{"oneOf":[{"type":"string","format":"email"},{"type":"object","required":["address"],"properties":{"name":{"type":"string"},"address":{"type":"string","format":"email"}}}]},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string","description":"Sent as written"},"in_reply_to":{"type":"string","example":"<abc@acme.com>"},"references":{"type":"array","items":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"X-… headers only"},"attachments":{"type":"array","items":{"type":"object","required":["filename","content"],"properties":{"filename":{"type":"string"},"content":{"type":"string","format":"byte","description":"base64"},"content_type":{"type":"string"}}},"description":"25 MiB in total"},"save_to_sent":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Idempotent replay: the first submission","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","sending","sent","failed"]},"message_id":{"type":"string","description":"RFC 5322 Message-ID of the sent message"},"from":{"type":"string"},"recipients":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"attempts":{"type":"integer"},"last_error":{"type":["string","null"]},"smtp_response":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"}}}}}},"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","sending","sent","failed"]},"message_id":{"type":"string","description":"RFC 5322 Message-ID of the sent message"},"from":{"type":"string"},"recipients":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"attempts":{"type":"integer"},"last_error":{"type":["string","null"]},"smtp_response":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing, invalid or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Scope missing, or mailbox / From not granted to this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"413":{"description":"Message too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Hourly quota of the key reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/messages/{id}":{"get":{"summary":"Status of a sent message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","sending","sent","failed"]},"message_id":{"type":"string","description":"RFC 5322 Message-ID of the sent message"},"from":{"type":"string"},"recipients":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"attempts":{"type":"integer"},"last_error":{"type":["string","null"]},"smtp_response":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"description":"Missing, invalid or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Scope missing, or mailbox / From not granted to this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Unknown, or another key's"}}}},"/mailboxes/{address}/folders":{"get":{"summary":"Folders with counts (read scope)","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"description":"A mailbox this key was granted"}],"responses":{"200":{"description":"Folders"},"401":{"description":"Missing, invalid or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Scope missing, or mailbox / From not granted to this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"External mailbox out of reach: mailbox_disconnected (its provider refused the password; an admin must enter a new one), mail_host_unavailable (its server is unreachable; see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/mailboxes/{address}/messages":{"get":{"summary":"List messages, newest first (read scope)","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"description":"A mailbox this key was granted"},{"name":"folder","in":"query","schema":{"type":"string","default":"INBOX"}},{"name":"unseen","in":"query","schema":{"type":"boolean"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"integer"},"description":"next_cursor of the previous page"}],"responses":{"200":{"description":"{ messages, next_cursor }"},"401":{"description":"Missing, invalid or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Scope missing, or mailbox / From not granted to this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"External mailbox out of reach: mailbox_disconnected (its provider refused the password; an admin must enter a new one), mail_host_unavailable (its server is unreachable; see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/mailboxes/{address}/messages/{id}":{"get":{"summary":"One message: parsed, HTML sanitised; ?format=raw for the RFC 822 source","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"description":"A mailbox this key was granted"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque message id from a list (folder + UIDVALIDITY + UID)"},{"name":"format","in":"query","schema":{"type":"string","enum":["raw"]}}],"responses":{"200":{"description":"Message"},"401":{"description":"Missing, invalid or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Scope missing, or mailbox / From not granted to this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Unknown or stale id"},"503":{"description":"External mailbox out of reach: mailbox_disconnected (its provider refused the password; an admin must enter a new one), mail_host_unavailable (its server is unreachable; see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"patch":{"summary":"Mark read/flagged, or move (answers the id in the new folder)","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"description":"A mailbox this key was granted"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque message id from a list (folder + UIDVALIDITY + UID)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seen":{"type":"boolean"},"flagged":{"type":"boolean"},"move_to":{"type":"string"}}}}}},"responses":{"200":{"description":"Moved: { id }"},"204":{"description":"Done"},"401":{"description":"Missing, invalid or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Scope missing, or mailbox / From not granted to this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"External mailbox out of reach: mailbox_disconnected (its provider refused the password; an admin must enter a new one), mail_host_unavailable (its server is unreachable; see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/mailboxes/{address}/messages/{id}/attachments/{index}":{"get":{"summary":"Download an attachment","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"description":"A mailbox this key was granted"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque message id from a list (folder + UIDVALIDITY + UID)"},{"name":"index","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The file"},"401":{"description":"Missing, invalid or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Scope missing, or mailbox / From not granted to this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"External mailbox out of reach: mailbox_disconnected (its provider refused the password; an admin must enter a new one), mail_host_unavailable (its server is unreachable; see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/mailboxes/{address}/messages/{id}/reply":{"post":{"summary":"Reply (send + read scopes): threading headers set, original marked answered once sent","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"description":"A mailbox this key was granted"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque message id from a list (folder + UIDVALIDITY + UID)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"html":{"type":"string"},"reply_all":{"type":"boolean"},"attachments":{"type":"array","items":{"type":"object","required":["filename","content"],"properties":{"filename":{"type":"string"},"content":{"type":"string","format":"byte","description":"base64"},"content_type":{"type":"string"}}}},"save_to_sent":{"type":"boolean"}}}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","sending","sent","failed"]},"message_id":{"type":"string","description":"RFC 5322 Message-ID of the sent message"},"from":{"type":"string"},"recipients":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"attempts":{"type":"integer"},"last_error":{"type":["string","null"]},"smtp_response":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"description":"Missing, invalid or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Scope missing, or mailbox / From not granted to this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"External mailbox out of reach: mailbox_disconnected (its provider refused the password; an admin must enter a new one), mail_host_unavailable (its server is unreachable; see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}