{"openapi":"3.1.0","info":{"title":"CherryMail Customer API","version":"1.0.0","description":"Customer email and account management. Mail content requires an explicit mailbox grant. API access does not bypass plan limits."},"servers":[{"url":"https://cherrymail.net/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A cm_rest_ credential created in the CherryMail account portal."}}},"paths":{"/account/":{"get":{"operationId":"account_get","summary":"Read account status, plan and storage usage.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"name":{"type":"string"},"status":{"type":"string","enum":["early-access","active","suspended"]},"usage_bytes":{"type":"number","description":"Account storage usage in bytes."},"plan":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"storage_gb":{"type":"number"}},"required":["name","storage_gb"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","status","usage_bytes","plan"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"id":2,"name":"Example company","status":"active","usage_bytes":1048576,"plan":{"name":"Starter","storage_gb":10}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/domains/":{"get":{"operationId":"domains_list","summary":"List domains in this account.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque next_cursor from a previous resource-list response."}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"name":{"type":"string","description":"Domain name."},"status":{"type":"string","enum":["pending","verified"]},"provisioningState":{"anyOf":[{"type":"string","enum":["pending","working","ready","error","deleting","deleted"]},{"type":"null"}]},"checks":{"type":"object","properties":{"ownership":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"mx":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"spf":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"dkim":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"dmarc":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false}},"required":["ownership","mx","spf","dkim","dmarc"],"additionalProperties":false,"description":"Current ownership and mail DNS checks."},"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Resource creation time."},"updatedAt":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Last resource update time."}},"required":["id","name","status","checks","createdAt","updatedAt"],"additionalProperties":false},"description":"Resource rows in this page."},"next_cursor":{"description":"Opaque cursor for the next page; null when this is the last page.","type":["string","null"]}},"required":["items","next_cursor"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"items":[{"id":7,"name":"example.com","status":"verified","provisioningState":"ready","checks":{"ownership":{"status":"pass","detail":"OWNERSHIP record verified."},"mx":{"status":"pass","detail":"MX record verified."},"spf":{"status":"pass","detail":"SPF record verified."},"dkim":{"status":"pass","detail":"DKIM record verified."},"dmarc":{"status":"pass","detail":"DMARC record verified."}},"createdAt":"2026-10-25T17:00:00.000Z","updatedAt":"2026-10-25T17:00:00.000Z"}],"next_cursor":"Nw"},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"empty":{"summary":"Empty result","value":{"data":{"items":[],"next_cursor":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"post":{"operationId":"domains_create","summary":"Reserve a domain. Publish the returned ownership records before verification.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":253}},"required":["domain"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"domains","resource_id":7,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/domains/{id}/":{"get":{"operationId":"domains_get","summary":"Read a domain and its manual DNS setup records.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"name":{"type":"string","description":"Domain name."},"status":{"type":"string","enum":["pending","verified"]},"provisioningState":{"anyOf":[{"type":"string","enum":["pending","working","ready","error","deleting","deleted"]},{"type":"null"}]},"checks":{"type":"object","properties":{"ownership":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"mx":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"spf":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"dkim":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"dmarc":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false}},"required":["ownership","mx","spf","dkim","dmarc"],"additionalProperties":false,"description":"Current ownership and mail DNS checks."},"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Resource creation time."},"updatedAt":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Last resource update time."},"dns_records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["TXT","MX"]},"host":{"description":"Record name; null while a DKIM selector is unavailable.","type":["string","null"]},"value":{"description":"Record value; null until the setting or signing key is available.","type":["string","null"]},"priority":{"description":"MX priority, present only on MX records.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","host","value"],"additionalProperties":false},"description":"Records to publish manually. Null DKIM values indicate native signing is not ready."}},"required":["id","name","status","checks","createdAt","updatedAt","dns_records"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"id":7,"name":"example.com","status":"verified","provisioningState":"ready","checks":{"ownership":{"status":"pass","detail":"OWNERSHIP record verified."},"mx":{"status":"pass","detail":"MX record verified."},"spf":{"status":"pass","detail":"SPF record verified."},"dkim":{"status":"pass","detail":"DKIM record verified."},"dmarc":{"status":"pass","detail":"DMARC record verified."}},"createdAt":"2026-10-25T17:00:00.000Z","updatedAt":"2026-10-25T17:00:00.000Z","dns_records":[{"type":"TXT","host":"_cherrymail.example.com","value":"cherrymail-verify=example-verification-token"},{"type":"MX","host":"example.com","value":"mail.cherrymail.net","priority":10},{"type":"TXT","host":"example.com","value":"v=spf1 mx -all"},{"type":"TXT","host":"_dmarc.example.com","value":"v=DMARC1; p=none"},{"type":"TXT","host":"dkim._domainkey.example.com","value":"v=DKIM1; k=rsa; p=YOUR_DOMAIN_PUBLIC_KEY"}]},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"delete":{"operationId":"domains_delete","summary":"Remove an empty domain. Requires approval in MCP.","description":"Required permission: delete. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmDomain":{"type":"string","maxLength":253}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"domains","resource_id":7,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The delete permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/domains/{id}/dns/":{"get":{"operationId":"domains_get_dns","summary":"Read a domain and its manual DNS setup records.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"name":{"type":"string","description":"Domain name."},"status":{"type":"string","enum":["pending","verified"]},"provisioningState":{"anyOf":[{"type":"string","enum":["pending","working","ready","error","deleting","deleted"]},{"type":"null"}]},"checks":{"type":"object","properties":{"ownership":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"mx":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"spf":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"dkim":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false},"dmarc":{"type":"object","properties":{"status":{"type":"string","enum":["waiting","pass","fail"]},"detail":{"type":["string","null"]}},"required":["status"],"additionalProperties":false}},"required":["ownership","mx","spf","dkim","dmarc"],"additionalProperties":false,"description":"Current ownership and mail DNS checks."},"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Resource creation time."},"updatedAt":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Last resource update time."},"dns_records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["TXT","MX"]},"host":{"description":"Record name; null while a DKIM selector is unavailable.","type":["string","null"]},"value":{"description":"Record value; null until the setting or signing key is available.","type":["string","null"]},"priority":{"description":"MX priority, present only on MX records.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","host","value"],"additionalProperties":false},"description":"Records to publish manually. Null DKIM values indicate native signing is not ready."}},"required":["id","name","status","checks","createdAt","updatedAt","dns_records"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"id":7,"name":"example.com","status":"verified","provisioningState":"ready","checks":{"ownership":{"status":"pass","detail":"OWNERSHIP record verified."},"mx":{"status":"pass","detail":"MX record verified."},"spf":{"status":"pass","detail":"SPF record verified."},"dkim":{"status":"pass","detail":"DKIM record verified."},"dmarc":{"status":"pass","detail":"DMARC record verified."}},"createdAt":"2026-10-25T17:00:00.000Z","updatedAt":"2026-10-25T17:00:00.000Z","dns_records":[{"type":"TXT","host":"_cherrymail.example.com","value":"cherrymail-verify=example-verification-token"},{"type":"MX","host":"example.com","value":"mail.cherrymail.net","priority":10},{"type":"TXT","host":"example.com","value":"v=spf1 mx -all"},{"type":"TXT","host":"_dmarc.example.com","value":"v=DMARC1; p=none"},{"type":"TXT","host":"dkim._domainkey.example.com","value":"v=DKIM1; k=rsa; p=YOUR_DOMAIN_PUBLIC_KEY"}]},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/domains/{id}/verify/":{"post":{"operationId":"domains_verify","summary":"Check published DNS records and queue provisioning when ownership is verified.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"domains","resource_id":7,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/":{"get":{"operationId":"mailboxes_list","summary":"List mailbox provisioning metadata, without email content.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque next_cursor from a previous resource-list response."}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"address":{"type":"string","description":"Mailbox email address."},"domain":{"description":"Domain ID, or null for the included CherryMail address.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"displayName":{"type":["string","null"]},"quotaMb":{"description":"Optional mailbox storage cap in MiB.","type":["number","null"]},"usageBytes":{"description":"Measured mailbox storage in bytes.","type":["number","null"]},"status":{"type":"string","enum":["pending","active","suspended"]},"provisioningState":{"anyOf":[{"type":"string","enum":["pending","working","ready","error","deleting","deleted"]},{"type":"null"}]},"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Resource creation time."},"updatedAt":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Last resource update time."}},"required":["id","address","status","createdAt","updatedAt"],"additionalProperties":false},"description":"Resource rows in this page."},"next_cursor":{"description":"Opaque cursor for the next page; null when this is the last page.","type":["string","null"]}},"required":["items","next_cursor"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"items":[{"id":123,"address":"hello@example.com","domain":7,"displayName":"Customer support","quotaMb":1024,"usageBytes":524288,"status":"active","provisioningState":"ready","createdAt":"2026-10-25T17:00:00.000Z","updatedAt":"2026-10-25T17:00:00.000Z"}],"next_cursor":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"empty":{"summary":"Empty result","value":{"data":{"items":[],"next_cursor":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"post":{"operationId":"mailboxes_create","summary":"Create a mailbox on a verified domain.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"localPart":{"type":"string","minLength":1,"maxLength":64},"displayName":{"type":"string","maxLength":120},"quotaMb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["domain","localPart"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"mailboxes","resource_id":123,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{id}/":{"get":{"operationId":"mailboxes_get","summary":"Read mailbox provisioning metadata without email content.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"address":{"type":"string","description":"Mailbox email address."},"domain":{"description":"Domain ID, or null for the included CherryMail address.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"displayName":{"type":["string","null"]},"quotaMb":{"description":"Optional mailbox storage cap in MiB.","type":["number","null"]},"usageBytes":{"description":"Measured mailbox storage in bytes.","type":["number","null"]},"status":{"type":"string","enum":["pending","active","suspended"]},"provisioningState":{"anyOf":[{"type":"string","enum":["pending","working","ready","error","deleting","deleted"]},{"type":"null"}]},"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Resource creation time."},"updatedAt":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Last resource update time."}},"required":["id","address","status","createdAt","updatedAt"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"id":123,"address":"hello@example.com","domain":7,"displayName":"Customer support","quotaMb":1024,"usageBytes":524288,"status":"active","provisioningState":"ready","createdAt":"2026-10-25T17:00:00.000Z","updatedAt":"2026-10-25T17:00:00.000Z"},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"patch":{"operationId":"mailboxes_update","summary":"Change mailbox display name or storage cap.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","maxLength":120},"quotaMb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"mailboxes","resource_id":123,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"delete":{"operationId":"mailboxes_delete","summary":"Permanently remove a mailbox and its contents. Requires approval in MCP.","description":"Required permission: delete. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmAddress":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["confirmAddress"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"mailboxes","resource_id":123,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The delete permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/free-address/":{"post":{"operationId":"mailboxes_claim","summary":"Claim the account's one included CherryMail address.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"freeAddress":{"type":"string","minLength":1,"maxLength":64}},"required":["freeAddress"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"mailboxes","resource_id":123,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/aliases/":{"get":{"operationId":"aliases_list","summary":"List forwarding aliases.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque next_cursor from a previous resource-list response."}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"address":{"type":"string"},"domain":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"destinations":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"id":{"description":"Payload destination-row ID, when present.","type":["string","null"]}},"required":["address"],"additionalProperties":false},"description":"Forwarding destinations as objects, not plain strings."},"status":{"type":"string","enum":["pending","active","suspended"]},"provisioningState":{"anyOf":[{"type":"string","enum":["pending","working","ready","error","deleting","deleted"]},{"type":"null"}]},"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Resource creation time."},"updatedAt":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Last resource update time."}},"required":["id","address","domain","destinations","status","createdAt","updatedAt"],"additionalProperties":false},"description":"Resource rows in this page."},"next_cursor":{"description":"Opaque cursor for the next page; null when this is the last page.","type":["string","null"]}},"required":["items","next_cursor"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"items":[{"id":12,"address":"support@example.com","domain":7,"destinations":[{"address":"hello@example.com","id":"68d13a3f9d8c154bd7aa1111"}],"status":"active","provisioningState":"ready","createdAt":"2026-10-25T17:00:00.000Z","updatedAt":"2026-10-25T17:00:00.000Z"}],"next_cursor":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"empty":{"summary":"Empty result","value":{"data":{"items":[],"next_cursor":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"post":{"operationId":"aliases_create","summary":"Create a forwarding alias on a verified domain.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"localPart":{"type":"string","minLength":1,"maxLength":64},"destinations":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"required":["domain","localPart","destinations"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"aliases","resource_id":12,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/aliases/{id}/":{"get":{"operationId":"aliases_get","summary":"Read a forwarding alias and its provisioning status.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"address":{"type":"string"},"domain":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"destinations":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"id":{"description":"Payload destination-row ID, when present.","type":["string","null"]}},"required":["address"],"additionalProperties":false},"description":"Forwarding destinations as objects, not plain strings."},"status":{"type":"string","enum":["pending","active","suspended"]},"provisioningState":{"anyOf":[{"type":"string","enum":["pending","working","ready","error","deleting","deleted"]},{"type":"null"}]},"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Resource creation time."},"updatedAt":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Last resource update time."}},"required":["id","address","domain","destinations","status","createdAt","updatedAt"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"id":12,"address":"support@example.com","domain":7,"destinations":[{"address":"hello@example.com","id":"68d13a3f9d8c154bd7aa1111"}],"status":"active","provisioningState":"ready","createdAt":"2026-10-25T17:00:00.000Z","updatedAt":"2026-10-25T17:00:00.000Z"},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"patch":{"operationId":"aliases_update","summary":"Change an alias forwarding destination list.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destinations":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"required":["destinations"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"aliases","resource_id":12,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"delete":{"operationId":"aliases_delete","summary":"Remove a forwarding alias. Requires approval in MCP.","description":"Required permission: delete. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmAddress":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["confirmAddress"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Accepted; awaiting readiness","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"resource_kind":"aliases","resource_id":12,"state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The delete permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/folders/":{"get":{"operationId":"folders_list","summary":"List folders in an explicitly granted mailbox.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"folders":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Full folder path for later mail operations."},"name":{"type":"string"},"delimiter":{"description":"Folder hierarchy delimiter; omitted when the native server reports NIL.","type":"string"},"specialUse":{"description":"IMAP special-use flag, such as \\Sent or \\Trash; null for an ordinary folder.","type":["string","null"]}},"required":["path","name","specialUse"],"additionalProperties":false}}},"required":["folders"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"folders":[{"path":"INBOX","name":"INBOX","delimiter":"/","specialUse":"\\Inbox"},{"path":"Projects","name":"Projects","delimiter":"/","specialUse":null}]},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"empty":{"summary":"Empty result","value":{"data":{"folders":[]},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"post":{"operationId":"folders_create","summary":"Create a mailbox folder.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},"required":["folder"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"folder":{"type":"string"},"created":{"type":"boolean","const":true}},"required":["folder","created"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"folder":"Projects","created":true}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/messages/":{"get":{"operationId":"messages_list","summary":"Search messages with bounded pagination. Returns UIDVALIDITY for later operations.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"folder","in":"query","required":false,"schema":{"default":"INBOX","type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"uidValidity","in":"query","required":false,"schema":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},{"name":"subject","in":"query","required":false,"schema":{"type":"string","maxLength":200,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"text","in":"query","required":false,"schema":{"type":"string","maxLength":200,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"since","in":"query","required":false,"schema":{"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))$"}},{"name":"before","in":"query","required":false,"schema":{"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))$"}},{"name":"seen","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"flagged","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"uidValidity":{"type":"string","description":"Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message."},"messages":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},"subject":{"type":"string"},"from":{"type":"array","items":{"type":"object","properties":{"name":{"description":"Display name, when supplied by the message envelope.","type":"string"},"address":{"description":"Envelope address when present. A group label can use an empty string; group members are flattened into this array.","type":"string"}},"additionalProperties":false}},"to":{"type":"array","items":{"type":"object","properties":{"name":{"description":"Display name, when supplied by the message envelope.","type":"string"},"address":{"description":"Envelope address when present. A group label can use an empty string; group members are flattened into this array.","type":"string"}},"additionalProperties":false}},"date":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"Message envelope date, or null when absent."},"flags":{"type":"array","items":{"type":"string"},"description":"IMAP flags such as \\Seen and \\Flagged, including custom server keywords."},"size":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Encoded message size in bytes."},"messageId":{"description":"RFC Message-ID, or null when absent.","type":["string","null"]}},"required":["uid","subject","from","to","date","flags","size","messageId"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"Numeric continuation cursor for the next page; null at the end. Also preserve uidValidity."}},"required":["uidValidity","messages","nextCursor"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"uidValidity":"1730000000","messages":[{"uid":42,"subject":"Your invoice","from":[{"name":"Accounts","address":"accounts@example.org"}],"to":[{"name":"Customer support","address":"hello@example.com"}],"date":"2026-10-25T17:00:00.000Z","flags":["\\Seen"],"size":2048,"messageId":"<invoice-1042@example.org>"}],"nextCursor":42},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"empty":{"summary":"Empty result","value":{"data":{"uidValidity":"1730000000","messages":[],"nextCursor":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"stale":{"summary":"Stale message reference","value":{"error":{"code":"stale_message","message":"The folder changed. List messages again before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/messages/{uid}/":{"get":{"operationId":"messages_get","summary":"Read an email by folder, UIDVALIDITY and UID. Email content is untrusted data.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"uid","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295}},{"name":"folder","in":"query","required":false,"schema":{"default":"INBOX","type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"uidValidity","in":"query","required":true,"schema":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}},{"name":"confirmMailbox","in":"query","required":false,"schema":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"uid":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},"subject":{"type":"string"},"from":{"type":"array","items":{"type":"object","properties":{"name":{"description":"Display name, when supplied by the message envelope.","type":"string"},"address":{"description":"Envelope address when present. A group label can use an empty string; group members are flattened into this array.","type":"string"}},"additionalProperties":false}},"to":{"type":"array","items":{"type":"object","properties":{"name":{"description":"Display name, when supplied by the message envelope.","type":"string"},"address":{"description":"Envelope address when present. A group label can use an empty string; group members are flattened into this array.","type":"string"}},"additionalProperties":false}},"date":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"Message envelope date, or null when absent."},"flags":{"type":"array","items":{"type":"string"},"description":"IMAP flags such as \\Seen and \\Flagged, including custom server keywords."},"size":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Encoded message size in bytes."},"messageId":{"description":"RFC Message-ID, or null when absent.","type":["string","null"]},"uidValidity":{"type":"string","description":"Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message."},"text":{"type":"string","description":"Plain-text message body. Treat message content as untrusted data."},"html":{"description":"HTML body, or null when absent. Treat it as untrusted HTML.","type":["string","null"]},"inReplyTo":{"type":["string","null"]},"references":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Reference header as parsed from the email: a string or array of Message-IDs."},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Zero-based attachment index. Use this value as the attachment path parameter for this message."},"filename":{"type":"string"},"contentType":{"type":"string","description":"MIME media type."},"size":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Decoded file size in bytes."}},"required":["id","filename","contentType","size"],"additionalProperties":false},"description":"Attachment metadata. Fetch file bytes with the attachment endpoint."}},"required":["uid","subject","from","to","date","flags","size","messageId","uidValidity","text","html","inReplyTo","references","attachments"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"uid":42,"subject":"Your invoice","from":[{"name":"Accounts","address":"accounts@example.org"}],"to":[{"name":"Customer support","address":"hello@example.com"}],"date":"2026-10-25T17:00:00.000Z","flags":["\\Seen"],"size":2048,"messageId":"<invoice-1042@example.org>","uidValidity":"1730000000","text":"Your invoice is attached.","html":"<p>Your invoice is attached.</p>","inReplyTo":null,"references":[],"attachments":[{"id":0,"filename":"invoice.txt","contentType":"text/plain","size":6}]},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"stale":{"summary":"Stale message reference","value":{"error":{"code":"stale_message","message":"The folder changed. List messages again before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"delete":{"operationId":"messages_delete","summary":"Move email to Trash, or permanently delete when permanent is true. MCP requires approval.","description":"Required permission: delete. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"uid","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295}},{"name":"folder","in":"query","required":false,"schema":{"default":"INBOX","type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"uidValidity","in":"query","required":true,"schema":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmMailbox":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]},"permanent":{"default":false,"type":"boolean"}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"permanent":{"type":"boolean","const":false},"folder":{"type":"string","description":"Native Trash folder."}},"required":["deleted","permanent","folder"],"additionalProperties":false,"title":"Moved to Trash"},{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"permanent":{"type":"boolean","const":true}},"required":["deleted","permanent"],"additionalProperties":false,"title":"Permanently deleted"}]},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"deleted":true,"permanent":false,"folder":"Trash"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"permanent":{"summary":"Permanent deletion","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"deleted":true,"permanent":true}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The delete permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"stale":{"summary":"Stale message reference","value":{"error":{"code":"stale_message","message":"The folder changed. List messages again before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/messages/{uid}/attachments/{attachment}/":{"get":{"operationId":"messages_attachment","summary":"Retrieve a bounded email attachment as base64.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"uid","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295}},{"name":"attachment","in":"path","required":true,"schema":{"type":"integer","minimum":0,"maximum":999}},{"name":"folder","in":"query","required":false,"schema":{"default":"INBOX","type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"uidValidity","in":"query","required":true,"schema":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}},{"name":"confirmMailbox","in":"query","required":false,"schema":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"filename":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Decoded file size in bytes."},"content":{"type":"string","description":"Base64-encoded file bytes, not a download URL."}},"required":["filename","contentType","size","content"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"filename":"invoice.txt","contentType":"text/plain","size":6,"content":"SGVsbG8K"},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"attachment":{"summary":"Attachment index not found","value":{"error":{"code":"attachment_not_found","message":"Attachment does not exist","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"stale":{"summary":"Stale message reference","value":{"error":{"code":"stale_message","message":"The folder changed. List messages again before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/drafts/":{"post":{"operationId":"drafts_create","summary":"Store a draft without sending it.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]},"to":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},"cc":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},"bcc":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},"subject":{"type":"string","maxLength":998,"pattern":"^[^\\x00-\\x1f\\x7f]*$"},"text":{"type":"string","maxLength":1000000},"html":{"type":"string","maxLength":1000000},"attachments":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180,"pattern":"^[^\\x00-\\x1f\\x7f]*$"},"contentType":{"type":"string","maxLength":120,"allOf":[{"pattern":"^[^\\x00-\\x1f\\x7f]*$"},{"pattern":"^[a-z0-9.+-]+\\/[a-z0-9.+-]+$"}]},"content":{"type":"string","maxLength":7000000,"pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"}},"required":["filename","contentType","content"],"additionalProperties":false}},"inReplyTo":{"type":"string","maxLength":998,"pattern":"^[^\\x00-\\x1f\\x7f]*$"},"references":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":998,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}}},"required":["to","subject","text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"folder":{"type":"string"},"uid":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"Appended message UID, or null when the IMAP server did not return it."},"uidValidity":{"anyOf":[{"type":"string","description":"Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message."},{"type":"null"}]},"messageId":{"type":"string"},"state":{"type":"string","const":"draft"}},"required":["folder","uid","uidValidity","messageId","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"folder":"Drafts","uid":55,"uidValidity":"1730000000","messageId":"<draft-1042@cherrymail.net>","state":"draft"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"ambiguous":{"summary":"Submission outcome uncertain; inspect before retrying","value":{"error":{"code":"send_ambiguous","message":"Submission is ambiguous; inspect the mailbox before creating a different operation","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/send/":{"post":{"operationId":"messages_send","summary":"Submit email using the granted mailbox identity. MCP requires approval of exact recipients and content.","description":"Required permission: send. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]},"to":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},"cc":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},"bcc":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},"subject":{"type":"string","maxLength":998,"pattern":"^[^\\x00-\\x1f\\x7f]*$"},"text":{"type":"string","maxLength":1000000},"html":{"type":"string","maxLength":1000000},"attachments":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180,"pattern":"^[^\\x00-\\x1f\\x7f]*$"},"contentType":{"type":"string","maxLength":120,"allOf":[{"pattern":"^[^\\x00-\\x1f\\x7f]*$"},{"pattern":"^[a-z0-9.+-]+\\/[a-z0-9.+-]+$"}]},"content":{"type":"string","maxLength":7000000,"pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"}},"required":["filename","contentType","content"],"additionalProperties":false}},"inReplyTo":{"type":"string","maxLength":998,"pattern":"^[^\\x00-\\x1f\\x7f]*$"},"references":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":998,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}}},"required":["to","subject","text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","const":"submitted"},"messageId":{"type":"string","description":"RFC Message-ID assigned to this submission."},"accepted":{"type":"array","items":{"type":"string"},"description":"Recipients accepted by SMTP."},"rejected":{"type":"array","items":{"type":"string"},"description":"Recipients rejected by SMTP."},"sentCopy":{"anyOf":[{"type":"object","properties":{"folder":{"type":"string"},"uid":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"Appended message UID, or null when the IMAP server did not return it."},"uidValidity":{"anyOf":[{"type":"string","description":"Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message."},{"type":"null"}]},"state":{"type":"string","const":"stored"}},"required":["folder","uid","uidValidity","state"],"additionalProperties":false,"title":"Stored Sent copy"},{"type":"object","properties":{"state":{"type":"string","const":"uncertain"},"message":{"type":"string","description":"SMTP succeeded, but the Sent copy needs inspection. Do not resend the email."}},"required":["state","message"],"additionalProperties":false,"title":"Uncertain Sent copy"}]},"delivered":{"type":"boolean","const":false,"description":"SMTP acceptance does not prove delivery to the recipient."}},"required":["state","messageId","accepted","rejected","sentCopy","delivered"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"SMTP accepted","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"state":"submitted","messageId":"<submission-1042@cherrymail.net>","accepted":["recipient@example.com"],"rejected":[],"sentCopy":{"state":"stored","folder":"Sent","uid":87,"uidValidity":"1730000000"},"delivered":false}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"sentCopyUncertain":{"summary":"SMTP accepted; Sent copy uncertain","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"state":"submitted","messageId":"<submission-1042@cherrymail.net>","accepted":["recipient@example.com"],"rejected":[],"sentCopy":{"state":"uncertain","message":"Submission succeeded. Inspect Sent before adding a copy."},"delivered":false}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The send permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"ambiguous":{"summary":"Submission outcome uncertain; inspect before retrying","value":{"error":{"code":"send_ambiguous","message":"Submission is ambiguous; inspect the mailbox before creating a different operation","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/messages/{uid}/reply/":{"post":{"operationId":"messages_reply","summary":"Reply to an email, preserving its reference headers. MCP requires approval.","description":"Required permission: send. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"uid","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295}},{"name":"folder","in":"query","required":false,"schema":{"default":"INBOX","type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"uidValidity","in":"query","required":true,"schema":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmMailbox":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]},"text":{"type":"string","maxLength":1000000},"html":{"type":"string","maxLength":1000000},"attachments":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180,"pattern":"^[^\\x00-\\x1f\\x7f]*$"},"contentType":{"type":"string","maxLength":120,"allOf":[{"pattern":"^[^\\x00-\\x1f\\x7f]*$"},{"pattern":"^[a-z0-9.+-]+\\/[a-z0-9.+-]+$"}]},"content":{"type":"string","maxLength":7000000,"pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"}},"required":["filename","contentType","content"],"additionalProperties":false}}},"required":["text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","const":"submitted"},"messageId":{"type":"string","description":"RFC Message-ID assigned to this submission."},"accepted":{"type":"array","items":{"type":"string"},"description":"Recipients accepted by SMTP."},"rejected":{"type":"array","items":{"type":"string"},"description":"Recipients rejected by SMTP."},"sentCopy":{"anyOf":[{"type":"object","properties":{"folder":{"type":"string"},"uid":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"Appended message UID, or null when the IMAP server did not return it."},"uidValidity":{"anyOf":[{"type":"string","description":"Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message."},{"type":"null"}]},"state":{"type":"string","const":"stored"}},"required":["folder","uid","uidValidity","state"],"additionalProperties":false,"title":"Stored Sent copy"},{"type":"object","properties":{"state":{"type":"string","const":"uncertain"},"message":{"type":"string","description":"SMTP succeeded, but the Sent copy needs inspection. Do not resend the email."}},"required":["state","message"],"additionalProperties":false,"title":"Uncertain Sent copy"}]},"delivered":{"type":"boolean","const":false,"description":"SMTP acceptance does not prove delivery to the recipient."}},"required":["state","messageId","accepted","rejected","sentCopy","delivered"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"SMTP accepted","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"state":"submitted","messageId":"<submission-1042@cherrymail.net>","accepted":["recipient@example.com"],"rejected":[],"sentCopy":{"state":"stored","folder":"Sent","uid":87,"uidValidity":"1730000000"},"delivered":false}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"sentCopyUncertain":{"summary":"SMTP accepted; Sent copy uncertain","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"state":"submitted","messageId":"<submission-1042@cherrymail.net>","accepted":["recipient@example.com"],"rejected":[],"sentCopy":{"state":"uncertain","message":"Submission succeeded. Inspect Sent before adding a copy."},"delivered":false}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The send permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"stale":{"summary":"Stale message reference","value":{"error":{"code":"stale_message","message":"The folder changed. List messages again before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"ambiguous":{"summary":"Submission outcome uncertain; inspect before retrying","value":{"error":{"code":"send_ambiguous","message":"Submission is ambiguous; inspect the mailbox before creating a different operation","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/messages/{uid}/forward/":{"post":{"operationId":"messages_forward","summary":"Forward an email as quoted text to specified recipients. Source attachments are included only when explicitly supplied.","description":"Required permission: send. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"uid","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295}},{"name":"folder","in":"query","required":false,"schema":{"default":"INBOX","type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"uidValidity","in":"query","required":true,"schema":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmMailbox":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]},"to":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]}},"text":{"default":"","type":"string","maxLength":1000000},"attachments":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180,"pattern":"^[^\\x00-\\x1f\\x7f]*$"},"contentType":{"type":"string","maxLength":120,"allOf":[{"pattern":"^[^\\x00-\\x1f\\x7f]*$"},{"pattern":"^[a-z0-9.+-]+\\/[a-z0-9.+-]+$"}]},"content":{"type":"string","maxLength":7000000,"pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"}},"required":["filename","contentType","content"],"additionalProperties":false}}},"required":["to"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","const":"submitted"},"messageId":{"type":"string","description":"RFC Message-ID assigned to this submission."},"accepted":{"type":"array","items":{"type":"string"},"description":"Recipients accepted by SMTP."},"rejected":{"type":"array","items":{"type":"string"},"description":"Recipients rejected by SMTP."},"sentCopy":{"anyOf":[{"type":"object","properties":{"folder":{"type":"string"},"uid":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"Appended message UID, or null when the IMAP server did not return it."},"uidValidity":{"anyOf":[{"type":"string","description":"Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message."},{"type":"null"}]},"state":{"type":"string","const":"stored"}},"required":["folder","uid","uidValidity","state"],"additionalProperties":false,"title":"Stored Sent copy"},{"type":"object","properties":{"state":{"type":"string","const":"uncertain"},"message":{"type":"string","description":"SMTP succeeded, but the Sent copy needs inspection. Do not resend the email."}},"required":["state","message"],"additionalProperties":false,"title":"Uncertain Sent copy"}]},"delivered":{"type":"boolean","const":false,"description":"SMTP acceptance does not prove delivery to the recipient."}},"required":["state","messageId","accepted","rejected","sentCopy","delivered"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"SMTP accepted","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"state":"submitted","messageId":"<submission-1042@cherrymail.net>","accepted":["recipient@example.com"],"rejected":[],"sentCopy":{"state":"stored","folder":"Sent","uid":87,"uidValidity":"1730000000"},"delivered":false}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"sentCopyUncertain":{"summary":"SMTP accepted; Sent copy uncertain","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"state":"submitted","messageId":"<submission-1042@cherrymail.net>","accepted":["recipient@example.com"],"rejected":[],"sentCopy":{"state":"uncertain","message":"Submission succeeded. Inspect Sent before adding a copy."},"delivered":false}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The send permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"stale":{"summary":"Stale message reference","value":{"error":{"code":"stale_message","message":"The folder changed. List messages again before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"ambiguous":{"summary":"Submission outcome uncertain; inspect before retrying","value":{"error":{"code":"send_ambiguous","message":"Submission is ambiguous; inspect the mailbox before creating a different operation","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/messages/{uid}/flags/":{"post":{"operationId":"messages_flags","summary":"Add or remove standard message flags.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"uid","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295}},{"name":"folder","in":"query","required":false,"schema":{"default":"INBOX","type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"uidValidity","in":"query","required":true,"schema":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmMailbox":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]},"add":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["\\Seen","\\Answered","\\Flagged","\\Draft"]}},"remove":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["\\Seen","\\Answered","\\Flagged","\\Draft"]}}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"updated":{"type":"boolean","const":true}},"required":["updated"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"updated":true}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"stale":{"summary":"Stale message reference","value":{"error":{"code":"stale_message","message":"The folder changed. List messages again before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/mailboxes/{mailboxId}/messages/{uid}/move/":{"post":{"operationId":"messages_move","summary":"Move an email to a folder in the same mailbox.","description":"Required permission: write. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"uid","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":4294967295}},{"name":"folder","in":"query","required":false,"schema":{"default":"INBOX","type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},{"name":"uidValidity","in":"query","required":true,"schema":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmMailbox":{"type":"string","maxLength":254,"allOf":[{"pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"pattern":"^[a-z0-9.!#$%&'+/=?^_`{|}~-]+@[a-z0-9.-]+$"}]},"destination":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\x00-\\x1f\\x7f]*$"}},"required":["destination"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"moved":{"type":"boolean","const":true},"folder":{"type":"string"},"uidValidity":{"type":"string","description":"Destination UIDVALIDITY. If the server omits UIDPLUS metadata this may be the literal undefined string; relist the destination before addressing its messages."},"uid":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"New UID in the destination folder; null when no UID mapping was returned. Relist the destination in that case."}},"required":["moved","folder","uidValidity","uid"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"moved":true,"folder":"Archive","uidValidity":"1730000000","uid":91}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The write permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"mailboxGrant":{"summary":"Mailbox access not granted","value":{"error":{"code":"mailbox_not_granted","message":"Mailbox consent or an account-owner grant is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}},"stale":{"summary":"Stale message reference","value":{"error":{"code":"stale_message","message":"The folder changed. List messages again before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/operations/{id}/":{"get":{"operationId":"operations_get","summary":"Read a durable API operation or approval-request receipt.","description":"Required permission: read. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","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)$"}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$"},"operation":{"type":"string","description":"Operation name, such as messages.send or domains.create."},"state":{"type":"string","enum":["running","pending","completed","failed","uncertain"],"description":"Execution/provisioning state. An uncertain submission may already have been accepted."},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"resource_kind":{"type":"string","enum":["domains","mailboxes","aliases"]},"resource_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"message":{"description":"Human-readable result, when returned.","type":"string"},"state":{"type":"string","const":"pending","description":"The resource change was accepted. Inspect the resource and operation for readiness; a reserved domain still needs ownership verification."}},"required":["resource_kind","resource_id","state"],"additionalProperties":false,"title":"Resource change"},{"type":"object","properties":{"state":{"type":"string","const":"submitted"},"messageId":{"type":"string","description":"RFC Message-ID assigned to this submission."},"accepted":{"type":"array","items":{"type":"string"},"description":"Recipients accepted by SMTP."},"rejected":{"type":"array","items":{"type":"string"},"description":"Recipients rejected by SMTP."},"sentCopy":{"anyOf":[{"type":"object","properties":{"folder":{"type":"string"},"uid":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"Appended message UID, or null when the IMAP server did not return it."},"uidValidity":{"anyOf":[{"type":"string","description":"Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message."},{"type":"null"}]},"state":{"type":"string","const":"stored"}},"required":["folder","uid","uidValidity","state"],"additionalProperties":false,"title":"Stored Sent copy"},{"type":"object","properties":{"state":{"type":"string","const":"uncertain"},"message":{"type":"string","description":"SMTP succeeded, but the Sent copy needs inspection. Do not resend the email."}},"required":["state","message"],"additionalProperties":false,"title":"Uncertain Sent copy"}]},"delivered":{"type":"boolean","const":false,"description":"SMTP acceptance does not prove delivery to the recipient."}},"required":["state","messageId","accepted","rejected","sentCopy","delivered"],"additionalProperties":false,"title":"SMTP submission"},{"type":"object","properties":{"folder":{"type":"string"},"uid":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"Appended message UID, or null when the IMAP server did not return it."},"uidValidity":{"anyOf":[{"type":"string","description":"Folder UIDVALIDITY. Preserve it with the mailbox, folder, and UID when addressing a message."},{"type":"null"}]},"messageId":{"type":"string"},"state":{"type":"string","const":"draft"}},"required":["folder","uid","uidValidity","messageId","state"],"additionalProperties":false,"title":"Stored draft"},{"type":"object","properties":{"folder":{"type":"string"},"created":{"type":"boolean","const":true}},"required":["folder","created"],"additionalProperties":false,"title":"Created folder"},{"type":"object","properties":{"updated":{"type":"boolean","const":true}},"required":["updated"],"additionalProperties":false,"title":"Updated flags"},{"type":"object","properties":{"moved":{"type":"boolean","const":true},"folder":{"type":"string"},"uidValidity":{"type":"string","description":"Destination UIDVALIDITY. If the server omits UIDPLUS metadata this may be the literal undefined string; relist the destination before addressing its messages."},"uid":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":4294967295},{"type":"null"}],"description":"New UID in the destination folder; null when no UID mapping was returned. Relist the destination in that case."}},"required":["moved","folder","uidValidity","uid"],"additionalProperties":false,"title":"Moved message"},{"anyOf":[{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"permanent":{"type":"boolean","const":false},"folder":{"type":"string","description":"Native Trash folder."}},"required":["deleted","permanent","folder"],"additionalProperties":false,"title":"Moved to Trash"},{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"permanent":{"type":"boolean","const":true}},"required":["deleted","permanent"],"additionalProperties":false,"title":"Permanently deleted"}]},{"type":"object","properties":{"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)$"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"mailbox_ids":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}},"required":["id","url","events","mailbox_ids"],"additionalProperties":false,"title":"Webhook subscription"},{"type":"object","properties":{"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)$"},"enabled":{"type":"boolean","const":false}},"required":["id","enabled"],"additionalProperties":false,"title":"Disabled webhook"},{"type":"object","properties":{"event_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)$","description":"Stable ID for the labelled webhook.test event."},"state":{"type":"string","const":"pending"}},"required":["event_id","state"],"additionalProperties":false,"title":"Test event queued"},{"type":"object","properties":{"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)$","description":"Existing delivery ID being replayed. Its event ID is unchanged."},"state":{"type":"string","const":"pending"}},"required":["id","state"],"additionalProperties":false,"title":"Replay queued"},{"type":"object","properties":{"approval_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)$"},"state":{"type":"string","const":"awaiting_approval"},"approval_url":{"type":"string"},"expires_in":{"type":"number","const":600}},"required":["approval_id","state","approval_url","expires_in"],"additionalProperties":false,"title":"MCP approval request"}]},{"type":"null"}],"description":"Result defined by the original operation. Null while no result is recorded. Webhook signing secrets are omitted."},"error_code":{"type":["string","null"]},"created_at":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["operation_id","operation","state","result","error_code","created_at","updated_at"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","operation":"messages.send","state":"completed","result":{"state":"submitted","messageId":"<submission-1042@cherrymail.net>","accepted":["recipient@example.com"],"rejected":[],"sentCopy":{"state":"stored","folder":"Sent","uid":87,"uidValidity":"1730000000"},"delivered":false},"error_code":null,"created_at":"2026-10-25T17:00:00.000Z","updated_at":"2026-10-25T17:00:00.000Z"},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The read permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/webhooks/":{"get":{"operationId":"webhooks_list","summary":"List your webhook subscriptions.","description":"Required permission: webhook. ","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"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)$"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"mailbox_ids":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"enabled":{"type":"boolean"},"created_at":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","url","events","mailbox_ids","enabled","created_at"],"additionalProperties":false},"description":"Up to 100 subscriptions. Signing secrets are never returned by this list."},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":[{"id":"5995bf69-cbf4-496e-b9d1-25c9d2095563","url":"https://your-app.example/cherrymail/events","events":["message.received"],"mailbox_ids":[123],"enabled":true,"created_at":"2026-10-25T17:00:00.000Z"}],"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"empty":{"summary":"Empty result","value":{"data":[],"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The webhook permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}},"post":{"operationId":"webhooks_create","summary":"Create a signed HTTPS webhook subscription. Save its one-time signing secret.","description":"Required permission: webhook. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"events":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","enum":["message.received","message.submitted","domain.verified","mailbox.ready","mailbox.deleted","alias.ready","alias.deleted","storage.80","storage.100","service.suspended","service.ready","webhook.test"]}},"mailbox_ids":{"default":[],"maxItems":100,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"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)$"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"mailbox_ids":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"signing_secret":{"description":"Shown only on the initial successful creation response. Omitted on idempotent replay and operation lookup; store it securely the first time.","type":"string"}},"required":["id","url","events","mailbox_ids"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"id":"5995bf69-cbf4-496e-b9d1-25c9d2095563","url":"https://your-app.example/cherrymail/events","events":["message.received"],"mailbox_ids":[123],"signing_secret":"cm_wh_example_only_store_your_actual_secret_securely"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"replay":{"summary":"Idempotent replay (secret omitted)","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"id":"5995bf69-cbf4-496e-b9d1-25c9d2095563","url":"https://your-app.example/cherrymail/events","events":["message.received"],"mailbox_ids":[123]}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The webhook permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/webhooks/{id}/":{"delete":{"operationId":"webhooks_delete","summary":"Disable a webhook subscription. MCP requires approval.","description":"Required permission: webhook. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","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)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"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)$"},"enabled":{"type":"boolean","const":false}},"required":["id","enabled"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"completed","result":{"id":"5995bf69-cbf4-496e-b9d1-25c9d2095563","enabled":false}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The webhook permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/webhooks/{id}/test/":{"post":{"operationId":"webhooks_test","summary":"Queue a labelled test webhook delivery.","description":"Required permission: webhook. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","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)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"event_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)$","description":"Stable ID for the labelled webhook.test event."},"state":{"type":"string","const":"pending"}},"required":["event_id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Queued","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"event_id":"659e5d31-0208-4e96-a34f-a9c6a9c3e3f3","state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The webhook permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/webhooks/{id}/deliveries/":{"get":{"operationId":"webhooks_deliveries","summary":"List the latest 100 webhook deliveries.","description":"Required permission: webhook. ","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","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)$"}}],"responses":{"200":{"description":"The requested resource or collection.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"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)$"},"event_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)$"},"state":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Most recent destination HTTP status; null when there was no HTTP response."},"last_error":{"type":["string","null"]},"next_attempt":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"created_at":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","event_id","state","attempts","status","last_error","next_attempt","created_at"],"additionalProperties":false},"description":"Latest 100 deliveries, newest first."},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Success","value":{"data":[{"id":"66f0407c-76f5-42a3-9ea6-c6e95297e130","event_id":"659e5d31-0208-4e96-a34f-a9c6a9c3e3f3","state":"delivered","attempts":1,"status":200,"last_error":null,"next_attempt":"2026-10-25T17:00:00.000Z","created_at":"2026-10-25T17:00:00.000Z"}],"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"empty":{"summary":"Empty result","value":{"data":[],"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The webhook permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}},"/webhooks/{id}/deliveries/{deliveryId}/replay/":{"post":{"operationId":"webhooks_replay","summary":"Replay a webhook delivery with its original event ID.","description":"Required permission: webhook. The response includes a durable operation_id. Query /operations/{id} for progress.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","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)$"}},{"name":"deliveryId","in":"path","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)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as the JSON body.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Per-credential limit and window.","schema":{"type":"string","example":"120;w=60"}},"RateLimit-Reset":{"description":"Rate-limit window in seconds.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"operation_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)$","description":"Durable operation ID. Use GET /operations/{id}/ to inspect it."},"state":{"type":"string","enum":["running","pending","completed","uncertain"]},"result":{"anyOf":[{"type":"object","properties":{"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)$","description":"Existing delivery ID being replayed. Its event ID is unchanged."},"state":{"type":"string","const":"pending"}},"required":["id","state"],"additionalProperties":false},{"type":"null"}],"description":"Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain."}},"required":["operation_id","state","result"],"additionalProperties":false},"request_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)$","description":"Request ID for support and correlation. Also returned in X-Request-ID."}},"required":["data","request_id"],"additionalProperties":false},"examples":{"success":{"summary":"Queued","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"pending","result":{"id":"66f0407c-76f5-42a3-9ea6-c6e95297e130","state":"pending"}},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"running":{"summary":"Concurrent request still running","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"running","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}},"uncertain":{"summary":"Uncertain operation receipt","value":{"data":{"operation_id":"6032a8b5-5ab8-4d3d-9104-d1e8162a1453","state":"uncertain","result":null},"request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Invalid input or missing idempotency key.","value":{"error":{"code":"invalid_input","message":"Check the documented input fields and types.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"401":{"description":"Missing, expired, or revoked bearer credential.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Missing, expired, or revoked bearer credential.","value":{"error":{"code":"invalid_token","message":"Use a valid CherryMail bearer credential.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"403":{"description":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Wrong credential purpose, insufficient scope, or missing mailbox grant.","value":{"error":{"code":"insufficient_scope","message":"The webhook permission is required.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"404":{"description":"Resource or message not found or unavailable to this integration.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource or message not found or unavailable to this integration.","value":{"error":{"code":"not_found","message":"Resource not found.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"409":{"description":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.","value":{"error":{"code":"idempotency_conflict","message":"This key was used for a different request.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"413":{"description":"Request or message exceeds the supported size.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Request or message exceeds the supported size.","value":{"error":{"code":"payload_too_large","message":"Request body exceeds the documented limit.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"429":{"description":"Rate limited. Honor Retry-After before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string","example":"60"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Rate limited. Honor Retry-After before retrying.","value":{"error":{"code":"rate_limited","message":"Wait one minute before retrying.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"500":{"description":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.","value":{"error":{"code":"internal_error","message":"The operation could not finish. Contact support with the request ID.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}},"503":{"description":"Integrations disabled or an upstream service unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","example":"no-store"}},"X-Request-ID":{"description":"Same request ID as error.request_id.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"request_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)$","description":"Request ID for support and correlation."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"error":{"summary":"Integrations disabled or an upstream service unavailable.","value":{"error":{"code":"integrations_disabled","message":"Customer integrations are not enabled.","request_id":"650f28e8-c344-42e4-ae43-c61539f83119"}}}}}}}}}}}}