{"openapi":"3.1.0","info":{"title":"Depot Control API","version":"1.0.0","description":"Provision domains and mailboxes. Every object belongs to exactly one account; a key can only ever reach its own."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Domain":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","minLength":3,"maxLength":253,"pattern":"^(?!-)[a-z0-9-]{1,63}(?<!-)(\\.(?!-)[a-z0-9-]{1,63}(?<!-))+$"},"status":{"type":"string","enum":["pending","verifying","active","failed"]},"lastVerifiedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"dnsReport":{"anyOf":[{"type":"object","properties":{"domain":{"type":"string"},"checks":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["mx","spf","dkim","dmarc","mta-sts","tls-rpt"]},"label":{"type":"string"},"expected":{"type":"string"},"found":{"type":"array","items":{"type":"string"}},"ok":{"type":"boolean"}},"required":["kind","label","expected","found","ok"],"additionalProperties":false}},"allOk":{"type":"boolean"},"checkedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["domain","checks","allOk","checkedAt"],"additionalProperties":false},{"type":"null"}]},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Send back as If-Match: \"<version>\" to make a write conditional."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","status","lastVerifiedAt","dnsReport","version","createdAt"],"additionalProperties":false},"Alias":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"id":{"type":"string"},"mailboxId":{"type":"string"},"domainId":{"type":"string"},"localPart":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9](?:[a-z0-9._+-]*[a-z0-9])?$"},"address":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","mailboxId","domainId","localPart","address","createdAt"],"additionalProperties":false},"CreateAlias":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"localPart":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9](?:[a-z0-9._+-]*[a-z0-9])?$"},"domainId":{"type":"string"}},"required":["localPart"],"additionalProperties":false},"Mailbox":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"id":{"type":"string"},"domainId":{"type":"string"},"localPart":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9](?:[a-z0-9._+-]*[a-z0-9])?$"},"address":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"displayName":{"type":"string"},"keepLocalCopy":{"type":"boolean"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Send back as If-Match: \"<version>\" to make a write conditional."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","domainId","localPart","address","displayName","keepLocalCopy","version","createdAt"],"additionalProperties":false},"MailboxWithCredential":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"id":{"type":"string"},"domainId":{"type":"string"},"localPart":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9](?:[a-z0-9._+-]*[a-z0-9])?$"},"address":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"displayName":{"type":"string"},"keepLocalCopy":{"type":"boolean"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Send back as If-Match: \"<version>\" to make a write conditional."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"password":{"type":"string","description":"Shown once. Not retrievable afterwards."},"imapHost":{"type":"string"},"imapPort":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"smtpHost":{"type":"string"},"smtpPort":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","domainId","localPart","address","displayName","keepLocalCopy","version","createdAt","password","imapHost","imapPort","smtpHost","smtpPort"],"additionalProperties":false},"UpdatedMailbox":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"id":{"type":"string"},"domainId":{"type":"string"},"localPart":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9](?:[a-z0-9._+-]*[a-z0-9])?$"},"address":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"displayName":{"type":"string"},"keepLocalCopy":{"type":"boolean"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Send back as If-Match: \"<version>\" to make a write conditional."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"password":{"description":"Present only when the password was rotated. Shown once.","type":"string"}},"required":["id","domainId","localPart","address","displayName","keepLocalCopy","version","createdAt"],"additionalProperties":false},"CreateDomain":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":253,"pattern":"^(?!-)[a-z0-9-]{1,63}(?<!-)(\\.(?!-)[a-z0-9-]{1,63}(?<!-))+$"}},"required":["name"],"additionalProperties":false},"CreateMailbox":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"localPart":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9](?:[a-z0-9._+-]*[a-z0-9])?$"},"displayName":{"default":"","type":"string","maxLength":255},"password":{"type":"string","minLength":12,"maxLength":255}},"required":["localPart","displayName"],"additionalProperties":false},"Forward":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"id":{"type":"string"},"mailboxId":{"type":"string"},"destination":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","mailboxId","destination","createdAt"],"additionalProperties":false},"CreateForward":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"destination":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["destination"],"additionalProperties":false},"UpdateMailbox":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"displayName":{"type":"string","maxLength":255},"keepLocalCopy":{"type":"boolean"},"password":{"type":"string","minLength":12,"maxLength":255},"rotatePassword":{"type":"boolean"}},"additionalProperties":false},"ServiceInfo":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"imapHost":{"type":"string"},"imapPort":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"smtpHost":{"type":"string"},"smtpPort":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["imapHost","imapPort","smtpHost","smtpPort"],"additionalProperties":false},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}}},"paths":{"/domains":{"get":{"summary":"List domains","responses":{"200":{"description":"Every domain in this account","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a domain","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDomain"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}":{"get":{"summary":"Get a domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The domain","headers":{"ETag":{"description":"The entity's current version. Send back as If-Match.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Remove a domain and its mailboxes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"The entity tag from a previous read, e.g. `\"3\"` — also available as `version` in the body. The write is refused with 412 if the object has changed since. Optional: omit it and the write proceeds unconditionally."}],"responses":{"200":{"description":"Deleted"},"400":{"description":"If-Match was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"If-Match did not match; nothing was changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}/dns":{"get":{"summary":"DNS records this domain needs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Required records"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}/verify":{"post":{"summary":"Check DNS and update the domain's status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"The entity tag from a previous read, e.g. `\"3\"` — also available as `version` in the body. The write is refused with 412 if the object has changed since. Optional: omit it and the write proceeds unconditionally."}],"responses":{"200":{"description":"The domain, with the verification report","headers":{"ETag":{"description":"The entity's current version. Send back as If-Match.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"If-Match was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"If-Match did not match; nothing was changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}/mailboxes":{"get":{"summary":"List mailboxes on a domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Mailboxes","content":{"application/json":{"schema":{"type":"object","properties":{"mailboxes":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a mailbox","description":"The password is returned exactly once and is not retrievable afterwards.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMailbox"}}}},"responses":{"201":{"description":"Created, with its one-time credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxWithCredential"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes":{"get":{"summary":"List every mailbox in the account","responses":{"200":{"description":"Mailboxes across all domains","content":{"application/json":{"schema":{"type":"object","properties":{"mailboxes":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/service-info":{"get":{"summary":"The account's IMAP/SMTP connection endpoints","description":"The same for every mailbox on the account. Lets a client configure itself — or adopt a pre-existing mailbox — without creating a mailbox to read the endpoints from its create response.","responses":{"200":{"description":"Connection endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInfo"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/aliases":{"get":{"summary":"List every alias in the account","parameters":[{"name":"domainId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Aliases, optionally narrowed to one domain","content":{"application/json":{"schema":{"type":"object","properties":{"aliases":{"type":"array","items":{"$ref":"#/components/schemas/Alias"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/aliases/{id}":{"delete":{"summary":"Remove an alias","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{id}/aliases":{"get":{"summary":"List a mailbox's extra addresses","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Aliases delivering into this mailbox","content":{"application/json":{"schema":{"type":"object","properties":{"aliases":{"type":"array","items":{"$ref":"#/components/schemas/Alias"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add an address that delivers into this mailbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAlias"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alias"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/forwards":{"get":{"summary":"List every forward in the account","description":"Where mail leaves to, across all mailboxes. The audit view.","parameters":[{"name":"mailboxId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Forwards, optionally narrowed to one mailbox","content":{"application/json":{"schema":{"type":"object","properties":{"forwards":{"type":"array","items":{"$ref":"#/components/schemas/Forward"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/forwards/{id}":{"delete":{"summary":"Stop forwarding to this destination","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{id}/forwards":{"get":{"summary":"Where this mailbox's mail is sent on to","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Forwards from this mailbox","content":{"application/json":{"schema":{"type":"object","properties":{"forwards":{"type":"array","items":{"$ref":"#/components/schemas/Forward"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Forward this mailbox's mail to another address","description":"The destination need not be a domain we host — that is the difference from an alias, which delivers *into* a mailbox. Whether a copy is also stored here is set per mailbox with `keepLocalCopy`, not per forward. A forward to a domain we do not host will not leave the server until outbound port 25 is unblocked; the rule is installed and correct regardless.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateForward"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forward"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{id}":{"get":{"summary":"Get a mailbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The mailbox","headers":{"ETag":{"description":"The entity's current version. Send back as If-Match.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update display name or rotate the password","description":"A rotated password is returned once in this response and is not retrievable afterwards.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"The entity tag from a previous read, e.g. `\"3\"` — also available as `version` in the body. The write is refused with 412 if the object has changed since. Optional: omit it and the write proceeds unconditionally."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMailbox"}}}},"responses":{"200":{"description":"The mailbox, with a new credential if one was set","headers":{"ETag":{"description":"The entity's current version. Send back as If-Match.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatedMailbox"}}}},"400":{"description":"If-Match was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"If-Match did not match; nothing was changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a mailbox and its stored mail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Replaying a mutation with the same key returns the original response and changes nothing."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"The entity tag from a previous read, e.g. `\"3\"` — also available as `version` in the body. The write is refused with 412 if the object has changed since. Optional: omit it and the write proceeds unconditionally."}],"responses":{"200":{"description":"Deleted"},"400":{"description":"If-Match was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Out of scope, suspended, or over quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"If-Match did not match; nothing was changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server refused or was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}