{"openapi":"3.1.0","info":{"title":"Qubrics API","version":"1.0.0","description":"Programmatic access to your Qubrics email infrastructure."},"servers":[{"url":"https://app.qubrics.com/api/v1","description":"API v1"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Qubrics API key. Use a root API key for Management API routes, or a mailbox credential for Mailbox API routes. Obtain keys from the dashboard under API Keys."},"oauth2":{"type":"oauth2","description":"Use the authorisation-code flow with S256 PKCE and resource=https://qubrics.com/api. The user selects the team, API access and mailboxes during consent. OAuth access tokens authenticate HTTP API requests; use separate credentials for SMTP and IMAP.","flows":{"authorizationCode":{"authorizationUrl":"https://app.qubrics.com/oauth/authorize","tokenUrl":"https://app.qubrics.com/oauth/token","refreshUrl":"https://app.qubrics.com/oauth/token","scopes":{"provider.create":"Add email provider accounts (Google, Microsoft, SMTP)","provider.read":"List/view provider accounts and connection status","provider.update":"Update provider settings, refresh tokens","provider.delete":"Remove provider accounts","provider.*":"All provider operations","key.create":"Create new API keys (both root and mailbox)","key.read":"List/view API keys and their metadata","key.revoke":"Revoke API keys","key.rotate":"Rotate API keys","key.*":"All key management operations","analytics.read":"View key usage analytics and verification logs","analytics.*":"All analytics operations","billing.read":"View balance, transactions, invoices","billing.topup":"Purchase balance top-ups","billing.auto_topup":"Configure auto top-up settings","billing.*":"All billing operations","domain.create":"Add sending domains","domain.read":"List/view domains and DNS status","domain.verify":"Trigger domain verification","domain.delete":"Remove domains","domain.*":"All domain operations","routing.create":"Create delivery groups","routing.read":"List/view delivery groups and routing rules","routing.update":"Update delivery group configuration","routing.delete":"Remove delivery groups","routing.*":"All routing operations","team.read":"View team settings and members","team.update":"Update team settings","team.members.invite":"Invite team members","team.members.remove":"Remove team members","team.members.roles":"Change member roles","team.*":"All team operations","logs.read":"View delivery logs","logs.*":"All log operations","mailbox.admin.create":"Create mailboxes (admin-level)","mailbox.admin.read":"List/view mailboxes (admin-level)","mailbox.admin.delete":"Delete mailboxes (admin-level)","mailbox.admin.manage":"Manage all mailbox settings","mailbox.admin.*":"All mailbox admin operations","webhook.create":"Create webhook subscriptions","webhook.read":"List/view webhook subscriptions","webhook.update":"Update webhook URL, event types, enabled flag","webhook.delete":"Delete webhook subscriptions","webhook.manage":"Rotate signing secret + send test events","webhook.*":"All webhook operations","email.send":"Send email through the HTTP API","email.receive":"Authorise email reception","mailbox.read":"Read mailbox contents (folders, messages)","mailbox.drafts.write":"Create and edit saved mailbox drafts","mailbox.settings.update":"Update own mailbox settings (signature, auto-reply)","calendar.read":"Read calendars and events in this mailbox","calendar.write":"Create calendars and create, edit and delete events in this mailbox"}}}}},"schemas":{"ResponseMeta":{"type":"object","properties":{"request_id":{"type":"string","example":"req_clxxxxxxxxxxxxxxxxxxxxxxxxx"}},"required":["request_id"],"additionalProperties":false},"CursorPagination":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string"}},"required":["has_more"],"additionalProperties":false},"SuccessEnvelope":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"meta":{"type":"object","properties":{},"additionalProperties":{}}},"required":["ok","meta"]},"ApiErrorDetail":{"type":"object","properties":{"field":{"type":"string","description":"Dot-path of the offending request field.","example":"recipient.email"},"code":{"type":"string","description":"Machine-readable issue code from the validator (e.g. zod issue code).","example":"invalid_string"},"message":{"type":"string","description":"Human-readable issue description."}},"required":["field","code","message"],"additionalProperties":false},"ApiError":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_parameter","missing_parameter","authentication_required","insufficient_permissions","not_found","conflict","limit_exceeded","idempotency_conflict","payload_too_large","validation_error","rate_limit_exceeded","service_unavailable","internal_error"],"description":"Machine-readable error code","example":"invalid_parameter"},"message":{"type":"string","description":"Human-readable error description"},"param":{"type":"string","description":"The parameter that caused the error"},"doc_url":{"type":"string","description":"Link to relevant documentation"},"retryable":{"type":"boolean","description":"Whether the caller may safely retry this request. 4xx are typically false (except 429); 5xx are typically true.","example":false},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiErrorDetail"},"description":"Accumulated per-field issues for validation errors. Only present on 400/422 responses."}},"required":["code","message","retryable"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string","example":"req_clxxxxxxxxxxxxxxxxxxxxxxxxx"}},"required":["request_id"],"additionalProperties":false}},"required":["ok","error","meta"],"additionalProperties":false},"MailboxSendPolicy":{"type":"object","properties":{"allowed_from":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":100,"default":[],"description":"Exact email addresses matched by this rule."},"domains":{"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(?!-)[a-z0-9-]{1,63}(?<!-)(?:\\.(?!-)[a-z0-9-]{1,63}(?<!-))+$"},"maxItems":100,"default":[],"description":"Exact domains; subdomains are not included automatically."},"own_address":{"type":"boolean","default":true,"description":"Allow the originating inbox address."}},"default":{},"additionalProperties":false,"description":"Allowed From addresses at this policy level."},"allowed_reply_to":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":100,"default":[],"description":"Exact email addresses matched by this rule."},"domains":{"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(?!-)[a-z0-9-]{1,63}(?<!-)(?:\\.(?!-)[a-z0-9-]{1,63}(?<!-))+$"},"maxItems":100,"default":[],"description":"Exact domains; subdomains are not included automatically."},"own_address":{"type":"boolean","default":true,"description":"Allow the originating inbox address."}},"default":{},"additionalProperties":false,"description":"Allowed Reply-To addresses at this policy level."},"alternate_from":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":100,"default":[],"description":"Ordered fallback From addresses; every policy level must explicitly allow each alternative."},"recipients":{"type":"object","properties":{"allow":{"type":["object","null"],"properties":{"addresses":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":100,"default":[],"description":"Exact email addresses matched by this rule."},"domains":{"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(?!-)[a-z0-9-]{1,63}(?<!-)(?:\\.(?!-)[a-z0-9-]{1,63}(?<!-))+$"},"maxItems":100,"default":[],"description":"Exact domains; subdomains are not included automatically."}},"default":null,"additionalProperties":false,"description":"Allowed recipients, or null for no allow-list restriction. An empty rule allows no recipients."},"deny":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":100,"default":[],"description":"Exact email addresses matched by this rule."},"domains":{"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(?!-)[a-z0-9-]{1,63}(?<!-)(?:\\.(?!-)[a-z0-9-]{1,63}(?<!-))+$"},"maxItems":100,"default":[],"description":"Exact domains; subdomains are not included automatically."}},"default":{},"additionalProperties":false,"description":"Blocked recipients; deny rules always take precedence."}},"default":{},"additionalProperties":false,"description":"Recipient restrictions applied to every To, Cc and Bcc address."}},"additionalProperties":false},"MailboxSendPolicySnapshot":{"type":"object","properties":{"policy":{"$ref":"#/components/schemas/MailboxSendPolicy"},"version":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Current policy version; also returned in ETag."}},"required":["policy","version"],"additionalProperties":false},"MailboxSendPolicyResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxSendPolicySnapshot"}},"required":["data"]}],"unevaluatedProperties":false},"ReplaceMailboxSendPolicy":{"type":"object","properties":{"policy":{"allOf":[{"$ref":"#/components/schemas/MailboxSendPolicy"},{"description":"Complete replacement policy; omitted settings return to their defaults."}]}},"required":["policy"],"additionalProperties":false},"Connection":{"type":"object","properties":{"team":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"credential":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["api_key","oauth","agent_token"],"example":"api_key"},"name":{"type":["string","null"]}},"required":["id","type","name"],"additionalProperties":false},"label":{"type":"string","description":"Display label for this connection."},"permissions":{"type":"array","items":{"type":"string"}},"mailboxes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["id","email"],"additionalProperties":false}}},"required":["team","credential","label","permissions","mailboxes"],"additionalProperties":false},"ConnectionResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/Connection"}},"required":["data"]}],"unevaluatedProperties":false},"ProviderTypeCounts":{"type":"object","properties":{"smtp":{"type":"number","description":"Number of SMTP accounts","example":6},"gmail_api":{"type":"number","description":"Number of Gmail API accounts","example":4},"outlook_api":{"type":"number","description":"Number of Outlook API accounts","example":2},"amazon_ses":{"type":"number","description":"Number of shared Amazon SES accounts","example":1}},"required":["smtp","gmail_api","outlook_api","amazon_ses"],"additionalProperties":false},"ProviderStatusCounts":{"type":"object","properties":{"active":{"type":"number","example":8},"inactive":{"type":"number","example":3},"error":{"type":"number","example":1},"pending":{"type":"number","example":0}},"required":["active","inactive","error","pending"],"additionalProperties":false},"ProviderStats":{"type":"object","properties":{"total":{"type":"number","description":"Total number of sending accounts","example":12},"active":{"type":"number","description":"Accounts with status 'active'","example":8},"inactive":{"type":"number","description":"Accounts with status 'inactive'","example":3},"error":{"type":"number","description":"Accounts with status 'error'","example":1},"pending":{"type":"number","description":"Accounts with status 'pending'","example":0},"by_type":{"$ref":"#/components/schemas/ProviderTypeCounts"},"by_status":{"$ref":"#/components/schemas/ProviderStatusCounts"}},"required":["total","active","inactive","error","pending","by_type","by_status"],"additionalProperties":false},"ProviderStatsResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/ProviderStats"}},"required":["data"]}],"unevaluatedProperties":false},"ProviderAllowedActions":{"type":"object","properties":{"update":{"type":"boolean"},"update_variables":{"type":"boolean"},"delete":{"type":"boolean"},"activate":{"type":"boolean"},"deactivate":{"type":"boolean"},"test":{"type":"boolean"}},"required":["update","update_variables","delete","activate","deactivate","test"],"additionalProperties":false},"ProviderQuotaRange":{"type":"object","properties":{"min":{"type":"integer","exclusiveMinimum":0,"example":60},"max":{"type":"integer","exclusiveMinimum":0,"example":60}},"required":["min","max"],"additionalProperties":false},"ProviderQuotas":{"type":"object","properties":{"per_second":{"anyOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}]},"per_minute":{"anyOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}]},"per_hour":{"anyOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}]},"per_day":{"anyOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}]}},"required":["per_second","per_minute","per_hour","per_day"],"additionalProperties":false},"ProviderListItem":{"type":"object","properties":{"id":{"type":"string","description":"Sending account public ID","example":"dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"name":{"type":"string","description":"Display name","example":"Transactional SMTP"},"type":{"type":"string","enum":["smtp","gmail_api","outlook_api","amazon_ses"],"description":"Sending account type. `amazon_ses` is the shared managed account.","example":"smtp"},"status":{"type":"string","enum":["active","inactive","error","pending"],"description":"Current sending account status.","example":"active"},"status_reason":{"type":["string","null"],"description":"Public-safe reason for the current status."},"is_active":{"type":"boolean","description":"Whether this account is enabled for sending."},"is_shared":{"type":"boolean","description":"True for the team's shared Amazon SES account."},"is_editable":{"type":"boolean","description":"False when the account is platform-managed."},"allowed_actions":{"$ref":"#/components/schemas/ProviderAllowedActions"},"smtp_host":{"type":["string","null"],"description":"SMTP host for custom SMTP accounts."},"smtp_port":{"type":["integer","null"],"description":"SMTP port for custom SMTP accounts."},"smtp_protocol":{"type":["string","null"],"description":"SMTP security mode."},"smtp_username":{"type":["string","null"],"description":"SMTP username for custom SMTP accounts."},"has_smtp_password":{"type":"boolean","description":"Whether a custom SMTP password is stored."},"from_email":{"type":["string","null"],"description":"Default From email address. Connected Google and Microsoft accounts always use their authorised account address."},"from_name":{"type":["string","null"],"description":"Default From display name."},"reply_to_email":{"type":["string","null"],"description":"Default Reply-To email address."},"reply_to_name":{"type":["string","null"],"description":"Default Reply-To display name."},"oauth_email":{"type":["string","null"],"description":"Connected account email for OAuth accounts."},"has_refresh_token":{"type":"boolean","description":"Whether an OAuth account has an active connection token."},"quotas":{"$ref":"#/components/schemas/ProviderQuotas"},"percentage":{"type":["integer","null"],"description":"Routing weight percentage.","example":100},"tracking_domain":{"type":["string","null"],"description":"Custom tracking hostname."},"created_at":{"type":"string","description":"ISO 8601 creation timestamp","example":"2026-05-25T02:18:00Z"},"updated_at":{"type":"string","description":"ISO 8601 last update timestamp","example":"2026-05-25T02:18:00Z"},"last_tested_at":{"type":["string","null"],"description":"Last connection test timestamp."},"last_used_at":{"type":["string","null"],"description":"Last send timestamp."}},"required":["id","name","type","status","status_reason","is_active","is_shared","is_editable","allowed_actions","smtp_host","smtp_port","smtp_protocol","smtp_username","has_smtp_password","from_email","from_name","reply_to_email","reply_to_name","oauth_email","has_refresh_token","quotas","percentage","tracking_domain","created_at","updated_at","last_tested_at","last_used_at"],"additionalProperties":false},"ProviderItemCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProviderListItem"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"ProviderVariables":{"type":"object","description":"Per-account string variables. PATCH omission preserves the current map, a supplied map replaces it, and an empty map clears it. Detail responses return an empty map when no variables are set.","maxProperties":50,"propertyNames":{"type":"string","maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"},"additionalProperties":{"type":"string","maxLength":4096},"example":{"signature_url":"https://example.com/signature"}},"ProviderItem":{"type":"object","properties":{"id":{"type":"string","description":"Sending account public ID","example":"dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"name":{"type":"string","description":"Display name","example":"Transactional SMTP"},"type":{"type":"string","enum":["smtp","gmail_api","outlook_api","amazon_ses"],"description":"Sending account type. `amazon_ses` is the shared managed account.","example":"smtp"},"status":{"type":"string","enum":["active","inactive","error","pending"],"description":"Current sending account status.","example":"active"},"status_reason":{"type":["string","null"],"description":"Public-safe reason for the current status."},"is_active":{"type":"boolean","description":"Whether this account is enabled for sending."},"is_shared":{"type":"boolean","description":"True for the team's shared Amazon SES account."},"is_editable":{"type":"boolean","description":"False when the account is platform-managed."},"allowed_actions":{"$ref":"#/components/schemas/ProviderAllowedActions"},"smtp_host":{"type":["string","null"],"description":"SMTP host for custom SMTP accounts."},"smtp_port":{"type":["integer","null"],"description":"SMTP port for custom SMTP accounts."},"smtp_protocol":{"type":["string","null"],"description":"SMTP security mode."},"smtp_username":{"type":["string","null"],"description":"SMTP username for custom SMTP accounts."},"has_smtp_password":{"type":"boolean","description":"Whether a custom SMTP password is stored."},"from_email":{"type":["string","null"],"description":"Default From email address. Connected Google and Microsoft accounts always use their authorised account address."},"from_name":{"type":["string","null"],"description":"Default From display name."},"reply_to_email":{"type":["string","null"],"description":"Default Reply-To email address."},"reply_to_name":{"type":["string","null"],"description":"Default Reply-To display name."},"oauth_email":{"type":["string","null"],"description":"Connected account email for OAuth accounts."},"has_refresh_token":{"type":"boolean","description":"Whether an OAuth account has an active connection token."},"quotas":{"$ref":"#/components/schemas/ProviderQuotas"},"percentage":{"type":["integer","null"],"description":"Routing weight percentage.","example":100},"tracking_domain":{"type":["string","null"],"description":"Custom tracking hostname."},"created_at":{"type":"string","description":"ISO 8601 creation timestamp","example":"2026-05-25T02:18:00Z"},"updated_at":{"type":"string","description":"ISO 8601 last update timestamp","example":"2026-05-25T02:18:00Z"},"last_tested_at":{"type":["string","null"],"description":"Last connection test timestamp."},"last_used_at":{"type":["string","null"],"description":"Last send timestamp."},"variables":{"$ref":"#/components/schemas/ProviderVariables"}},"required":["id","name","type","status","status_reason","is_active","is_shared","is_editable","allowed_actions","smtp_host","smtp_port","smtp_protocol","smtp_username","has_smtp_password","from_email","from_name","reply_to_email","reply_to_name","oauth_email","has_refresh_token","quotas","percentage","tracking_domain","created_at","updated_at","last_tested_at","last_used_at","variables"],"additionalProperties":false},"ProviderItemResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/ProviderItem"}},"required":["data"]}],"unevaluatedProperties":false},"ProviderCreateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"example":"Transactional SMTP"},"smtp_host":{"type":"string","minLength":1,"maxLength":255,"example":"smtp.example.com"},"smtp_port":{"type":"integer","minimum":1,"maximum":65535,"example":587},"smtp_protocol":{"type":"string","enum":["tls","ssl","none","starttls"],"example":"starttls"},"smtp_username":{"type":"string","minLength":1,"maxLength":255,"example":"api-user"},"smtp_password":{"type":"string","minLength":1,"maxLength":500,"example":"smtp-password"},"from_email":{"type":["string","null"],"maxLength":255,"format":"email","description":"Default From email address for an SMTP account.","example":"sender@example.com"},"from_name":{"type":["string","null"],"maxLength":255,"example":"Acme"},"reply_to_email":{"type":["string","null"],"maxLength":255,"format":"email","example":"support@example.com"},"reply_to_name":{"type":["string","null"],"maxLength":255,"example":"Support"},"quotas":{"type":"object","properties":{"per_second":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}],"description":"Quota value. Use a number for a fixed cap, a min/max range, or null to clear on PATCH."},"per_minute":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}],"description":"Quota value. Use a number for a fixed cap, a min/max range, or null to clear on PATCH."},"per_hour":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}],"description":"Quota value. Use a number for a fixed cap, a min/max range, or null to clear on PATCH."},"per_day":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}],"description":"Quota value. Use a number for a fixed cap, a min/max range, or null to clear on PATCH."}},"additionalProperties":false},"percentage":{"type":"integer","minimum":0,"maximum":100,"example":100},"tracking_domain":{"type":["string","null"],"maxLength":255,"example":"click.example.com"},"variables":{"$ref":"#/components/schemas/ProviderVariables"}},"required":["name","smtp_host","smtp_port","smtp_protocol","smtp_username","smtp_password"],"additionalProperties":false},"SharedAmazonSesLimitRequest":{"type":"object","properties":{"id":{"type":"string","example":"slir_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","enum":["pending","approved","denied","cancelled"]},"current_daily_limit":{"type":"integer","minimum":0},"current_daily_sent":{"type":"integer","minimum":0},"approved_daily_limit":{"type":["integer","null"],"exclusiveMinimum":0},"decision_note":{"type":["string","null"]},"created_at":{"type":"string"},"decided_at":{"type":["string","null"]}},"required":["id","status","current_daily_limit","current_daily_sent","approved_daily_limit","decision_note","created_at","decided_at"],"additionalProperties":false},"SharedAmazonSesLimit":{"type":"object","properties":{"provider_id":{"type":["string","null"]},"daily_limit":{"type":["integer","null"],"minimum":0},"sent_today":{"type":"integer","minimum":0},"threshold_usage":{"type":["integer","null"],"minimum":0},"usage_ratio":{"type":["number","null"]},"is_near_limit":{"type":"boolean"},"can_request_increase":{"type":"boolean"},"pending_request_id":{"type":["string","null"]}},"required":["provider_id","daily_limit","sent_today","threshold_usage","usage_ratio","is_near_limit","can_request_increase","pending_request_id"],"additionalProperties":false},"SharedAmazonSesLimitRequestCancel":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequest"},"limit":{"$ref":"#/components/schemas/SharedAmazonSesLimit"}},"required":["request","limit"],"additionalProperties":false},"SharedAmazonSesLimitRequestCancelResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequestCancel"}},"required":["data"]}],"unevaluatedProperties":false},"ProviderUpdateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"example":"Transactional SMTP"},"smtp_host":{"type":"string","minLength":1,"maxLength":255,"example":"smtp.example.com"},"smtp_port":{"type":"integer","minimum":1,"maximum":65535,"example":587},"smtp_protocol":{"type":"string","enum":["tls","ssl","none","starttls"],"example":"starttls"},"smtp_username":{"type":"string","minLength":1,"maxLength":255,"example":"api-user"},"from_email":{"type":["string","null"],"maxLength":255,"format":"email","description":"Default From email address for an SMTP account. Connected Google and Microsoft accounts keep their authorised account address.","example":"sender@example.com"},"from_name":{"type":["string","null"],"maxLength":255,"example":"Acme"},"reply_to_email":{"type":["string","null"],"maxLength":255,"format":"email","example":"support@example.com"},"reply_to_name":{"type":["string","null"],"maxLength":255,"example":"Support"},"quotas":{"type":"object","properties":{"per_second":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}],"description":"Quota value. Use a number for a fixed cap, a min/max range, or null to clear on PATCH."},"per_minute":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}],"description":"Quota value. Use a number for a fixed cap, a min/max range, or null to clear on PATCH."},"per_hour":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}],"description":"Quota value. Use a number for a fixed cap, a min/max range, or null to clear on PATCH."},"per_day":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"null"}],"description":"Quota value. Use a number for a fixed cap, a min/max range, or null to clear on PATCH."}},"additionalProperties":false},"percentage":{"type":"integer","minimum":0,"maximum":100,"example":100},"tracking_domain":{"type":["string","null"],"maxLength":255,"example":"click.example.com"},"variables":{"$ref":"#/components/schemas/ProviderVariables"},"smtp_password":{"type":"string","minLength":1,"maxLength":500,"example":"new-smtp-password"}},"additionalProperties":false},"ProviderDeleted":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false},"ProviderDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/ProviderDeleted"}},"required":["data"]}],"unevaluatedProperties":false},"ProviderTestResult":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Connection verified."},"latency_ms":{"type":"integer","minimum":0,"example":182},"tested_at":{"type":"string","example":"2026-05-25T02:18:00Z"}},"required":["success","message","latency_ms","tested_at"],"additionalProperties":false},"ProviderTestResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/ProviderTestResult"}},"required":["data"]}],"unevaluatedProperties":false},"ProviderUsageItem":{"type":"object","properties":{"provider_id":{"type":"string"},"sent_today":{"type":"integer","minimum":0},"total_7d":{"type":"integer","minimum":0},"sent_7d":{"type":"integer","minimum":0},"failed_7d":{"type":"integer","minimum":0},"rejected_7d":{"type":"integer","minimum":0},"pending_7d":{"type":"integer","minimum":0}},"required":["provider_id","sent_today","total_7d","sent_7d","failed_7d","rejected_7d","pending_7d"],"additionalProperties":false},"ProviderUsage":{"type":"object","properties":{"window_days":{"type":"number","enum":[7]},"providers":{"type":"array","items":{"$ref":"#/components/schemas/ProviderUsageItem"}}},"required":["window_days","providers"],"additionalProperties":false},"ProviderUsageResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/ProviderUsage"}},"required":["data"]}],"unevaluatedProperties":false},"ResourceLimitSnapshot":{"type":"object","properties":{"resource_type":{"type":"string","example":"sending_accounts"},"usage":{"type":"integer","minimum":0},"max_allowed":{"type":"integer","exclusiveMinimum":0},"reserved":{"type":"integer","minimum":0},"threshold_usage":{"type":"integer","minimum":0},"usage_ratio":{"type":"number"},"is_at_limit":{"type":"boolean"},"is_near_limit":{"type":"boolean"},"can_request_increase":{"type":"boolean"},"pending_request_id":{"type":["string","null"]}},"required":["resource_type","usage","max_allowed","reserved","threshold_usage","usage_ratio","is_at_limit","is_near_limit","can_request_increase","pending_request_id"],"additionalProperties":false},"ProviderLimits":{"type":"object","properties":{"sending_accounts":{"$ref":"#/components/schemas/ResourceLimitSnapshot"},"shared_amazon_ses":{"$ref":"#/components/schemas/SharedAmazonSesLimit"}},"required":["sending_accounts","shared_amazon_ses"],"additionalProperties":false},"ProviderLimitsResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/ProviderLimits"}},"required":["data"]}],"unevaluatedProperties":false},"SendingAccountLimitRequest":{"type":"object","properties":{"request_id":{"type":"string","example":"trir_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"limit":{"$ref":"#/components/schemas/ResourceLimitSnapshot"}},"required":["request_id","limit"],"additionalProperties":false},"SendingAccountLimitRequestResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SendingAccountLimitRequest"}},"required":["data"]}],"unevaluatedProperties":false},"SharedAmazonSesLimitRequestPage":{"type":"object","properties":{"limit":{"$ref":"#/components/schemas/SharedAmazonSesLimit"},"pending_request":{"anyOf":[{"$ref":"#/components/schemas/SharedAmazonSesLimitRequest"},{"type":"null"}]}},"required":["limit","pending_request"],"additionalProperties":false},"SharedAmazonSesLimitRequestPageResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequestPage"}},"required":["data"]}],"unevaluatedProperties":false},"SharedAmazonSesLimitRequestCreate":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequest"},"limit":{"$ref":"#/components/schemas/SharedAmazonSesLimit"}},"required":["request","limit"],"additionalProperties":false},"SharedAmazonSesLimitRequestCreateResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequestCreate"}},"required":["data"]}],"unevaluatedProperties":false},"EmailMetrics":{"type":"object","properties":{"summary":{"type":"object","properties":{"total":{"type":"number","example":15230},"sent":{"type":"number","example":14890},"failed":{"type":"number","example":210},"rejected":{"type":"number","example":80},"pending":{"type":"number","example":50}},"required":["total","sent","failed","rejected","pending"],"additionalProperties":false},"comparison":{"type":"object","properties":{"total":{"type":"number","example":15230},"sent":{"type":"number","example":14890},"failed":{"type":"number","example":210},"rejected":{"type":"number","example":80},"pending":{"type":"number","example":50},"change_pct":{"type":"object","properties":{"total":{"type":"number","example":8.01},"sent":{"type":"number","example":7.9},"failed":{"type":"number","example":10.53},"rejected":{"type":"number","example":33.33},"pending":{"type":"number","example":0}},"required":["total","sent","failed","rejected","pending"],"additionalProperties":false}},"required":["total","sent","failed","rejected","pending","change_pct"],"additionalProperties":false},"timeseries":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","example":"2026-03-19T00:00:00Z"},"total":{"type":"number"},"sent":{"type":"number"},"failed":{"type":"number"},"rejected":{"type":"number"},"pending":{"type":"number"}},"required":["timestamp","total","sent","failed","rejected","pending"],"additionalProperties":false}}},"required":["summary","comparison","timeseries"],"additionalProperties":false},"EmailMetricsResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/EmailMetrics"}},"required":["data"]}],"unevaluatedProperties":false},"DeliveryLogItem":{"type":"object","properties":{"id":{"type":"string","description":"Log public ID","example":"dlog_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"provider_id":{"type":["string","null"],"description":"Provider public ID"},"provider_name":{"type":["string","null"],"description":"Provider display name"},"delivery_group":{"type":["array","null"],"items":{"type":"string","minLength":6,"maxLength":128},"minItems":1,"maxItems":50,"description":"Applied per-message delivery group public IDs, or null for absent, ignored or historical hints"},"message_id":{"type":["string","null"],"description":"Email Message-ID header"},"from_email":{"type":["string","null"]},"sent_from_email":{"type":["string","null"],"description":"The actual from address used for delivery after transformation. NULL if no transformation occurred or for older log entries."},"to_email":{"type":["string","null"]},"subject":{"type":["string","null"]},"status":{"type":"string","enum":["pending","sent","failed","rejected"]},"status_reason":{"type":["string","null"]},"attempts":{"type":"number"},"sent_at":{"type":["string","null"],"description":"ISO 8601 timestamp when email was sent"},"size_bytes":{"type":["number","null"]},"created_at":{"type":"string","description":"ISO 8601 creation timestamp"},"recipient_count":{"type":["integer","null"],"minimum":0,"maximum":50,"description":"Total recipient occurrences, or null when no recipient snapshot exists"},"accepted_recipient_count":{"type":["integer","null"],"minimum":0,"maximum":50,"description":"Recipient occurrences accepted by the provider, or null when no recipient snapshot exists"},"rejected_recipient_count":{"type":["integer","null"],"minimum":0,"maximum":50,"description":"Recipient occurrences rejected by the provider, or null when no recipient snapshot exists"}},"required":["id","provider_id","provider_name","delivery_group","message_id","from_email","sent_from_email","to_email","subject","status","status_reason","attempts","sent_at","size_bytes","created_at","recipient_count","accepted_recipient_count","rejected_recipient_count"],"additionalProperties":false},"DeliveryLogItemCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryLogItem"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"DeliveryLogRecipient":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Recipient email address"},"type":{"type":["string","null"],"enum":["to","cc","bcc"],"description":"Recipient header type when known"},"status":{"type":"string","enum":["accepted","rejected"],"description":"Provider acceptance outcome"},"reason":{"type":["string","null"],"description":"Recipient-specific rejection reason when available"}},"required":["email","type","status","reason"],"additionalProperties":false},"DeliveryLogDetail":{"type":"object","properties":{"id":{"type":"string","description":"Log public ID","example":"dlog_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"provider_id":{"type":["string","null"],"description":"Provider public ID"},"provider_name":{"type":["string","null"],"description":"Provider display name"},"delivery_group":{"type":["array","null"],"items":{"type":"string","minLength":6,"maxLength":128},"minItems":1,"maxItems":50,"description":"Applied per-message delivery group public IDs, or null for absent, ignored or historical hints"},"message_id":{"type":["string","null"],"description":"Email Message-ID header"},"from_email":{"type":["string","null"]},"sent_from_email":{"type":["string","null"],"description":"The actual from address used for delivery after transformation. NULL if no transformation occurred or for older log entries."},"to_email":{"type":["string","null"]},"subject":{"type":["string","null"]},"status":{"type":"string","enum":["pending","sent","failed","rejected"]},"status_reason":{"type":["string","null"]},"attempts":{"type":"number"},"sent_at":{"type":["string","null"],"description":"ISO 8601 timestamp when email was sent"},"size_bytes":{"type":["number","null"]},"created_at":{"type":"string","description":"ISO 8601 creation timestamp"},"recipient_count":{"type":["integer","null"],"minimum":0,"maximum":50,"description":"Total recipient occurrences, or null when no recipient snapshot exists"},"accepted_recipient_count":{"type":["integer","null"],"minimum":0,"maximum":50,"description":"Recipient occurrences accepted by the provider, or null when no recipient snapshot exists"},"rejected_recipient_count":{"type":["integer","null"],"minimum":0,"maximum":50,"description":"Recipient occurrences rejected by the provider, or null when no recipient snapshot exists"},"recipients":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DeliveryLogRecipient"},"maxItems":50,"description":"Ordered recipient outcome snapshot for this send, or null when no snapshot exists"}},"required":["id","provider_id","provider_name","delivery_group","message_id","from_email","sent_from_email","to_email","subject","status","status_reason","attempts","sent_at","size_bytes","created_at","recipient_count","accepted_recipient_count","rejected_recipient_count","recipients"],"additionalProperties":false},"DeliveryLogItemResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/DeliveryLogDetail"}},"required":["data"]}],"unevaluatedProperties":false},"Balance":{"type":"object","properties":{"balance":{"type":"string","description":"Current spendable balance","example":"45.230000"},"balance_purchased":{"type":"string","example":"100.000000"},"balance_consumed":{"type":"string","example":"54.770000"},"currency":{"type":"string","enum":["USD"]},"auto_topup":{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold":{"type":["string","null"],"example":"10.000000"},"amount":{"type":["string","null"],"example":"50.000000"},"monthly_limit":{"type":["string","null"],"example":"200.000000"},"monthly_used":{"type":"string","example":"50.000000"}},"required":["enabled","threshold","amount","monthly_limit","monthly_used"],"additionalProperties":false}},"required":["balance","balance_purchased","balance_consumed","currency","auto_topup"],"additionalProperties":false},"BalanceResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/Balance"}},"required":["data"]}],"unevaluatedProperties":false},"SpendSummary":{"type":"object","properties":{"period_days":{"type":"number","example":30},"total_purchased":{"type":"string","example":"150.000000"},"total_consumed":{"type":"string","example":"54.770000"},"transaction_count":{"type":"number","example":23},"currency":{"type":"string","enum":["USD"]}},"required":["period_days","total_purchased","total_consumed","transaction_count","currency"],"additionalProperties":false},"SpendSummaryResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SpendSummary"}},"required":["data"]}],"unevaluatedProperties":false},"Transaction":{"type":"object","properties":{"id":{"type":"string","description":"Transaction public ID","example":"tx_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"amount":{"type":"string","description":"DECIMAL(19,6) amount","example":"-0.001500"},"type":{"type":"string","enum":["PURCHASE","USAGE","AUTO_TOPUP","REFUND","ADJUSTMENT"]},"description":{"type":"string"},"quantity":{"type":["number","null"],"description":"Item count (for USAGE transactions)"},"balance_before":{"type":["string","null"]},"balance_after":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO 8601 timestamp"}},"required":["id","amount","type","description","quantity","balance_before","balance_after","created_at"],"additionalProperties":false},"TransactionCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxDomainMxRecord":{"type":"object","properties":{"priority":{"type":"integer","example":10},"target":{"type":"string","example":"mail.qubrics.com"}},"required":["priority","target"],"additionalProperties":false},"MailboxDomainNamedMxRecord":{"type":"object","properties":{"name":{"type":"string","example":"bounce.acme.com"},"priority":{"type":"integer","example":10},"target":{"type":"string","example":"feedback-smtp.eu-central-1.amazonses.com"}},"required":["name","priority","target"],"additionalProperties":false,"description":"MX record for Amazon SES bounce handling"},"MailboxDomainNameValueRecord":{"type":"object","properties":{"name":{"type":"string","example":"_sendmux.acme.com"},"value":{"type":"string","example":"sendmux-verify=team_abc123"}},"required":["name","value"],"additionalProperties":false,"description":"SPF TXT record for the custom MAIL FROM subdomain"},"MailboxDomainMailFromRecords":{"type":"object","properties":{"mx":{"$ref":"#/components/schemas/MailboxDomainNamedMxRecord"},"spf":{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"}},"required":["mx","spf"],"additionalProperties":false,"description":"Custom MAIL FROM records for Amazon SES bounce handling"},"MailboxDomainDnsRecords":{"type":"object","properties":{"mx":{"type":"array","items":{"$ref":"#/components/schemas/MailboxDomainMxRecord"},"description":"MX records the customer must place. All point at Qubrics' inbound mail servers."},"mail_from":{"$ref":"#/components/schemas/MailboxDomainMailFromRecords"},"spf":{"allOf":[{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"},{"description":"SPF TXT record covering Amazon SES sending"}]},"dmarc":{"allOf":[{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"},{"description":"DMARC enforcement record (quarantine, no reporting)"}]},"dkim":{"type":"array","items":{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"},"description":"Three Amazon SES DKIM CNAME records"},"verification":{"allOf":[{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"},{"description":"Ownership-proof TXT record (Qubrics-specific)"}]}},"required":["mx","mail_from","spf","dmarc","dkim","verification"],"additionalProperties":false},"MailboxDomain":{"type":"object","properties":{"id":{"type":"string","description":"Public ID","example":"mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"domain":{"type":"string","description":"Fully qualified domain name","example":"mail.acme.com"},"mode":{"type":"string","enum":["send_only","send_receive"],"description":"`send_only` verifies outbound DNS only. `send_receive` also verifies MX records and can host mailboxes.","example":"send_receive"},"verification_status":{"type":"string","enum":["pending","verified","failed"],"description":"Current verification state"},"ses_identity_verification_status":{"type":["string","null"],"description":"Latest Amazon SES identity verification status"},"ses_verified_for_sending":{"type":["boolean","null"],"description":"Whether Amazon SES currently permits sending for this identity"},"ses_dkim_status":{"type":["string","null"],"description":"Amazon SES DKIM status (pending/success/failed/temporary_failure/not_started)"},"ses_dkim_signing_enabled":{"type":["boolean","null"],"description":"Whether Amazon SES DKIM signing is currently enabled for this identity"},"ses_identity_checked_at":{"type":["string","null"],"description":"ISO 8601 timestamp of the latest complete Amazon SES identity check"},"ses_mail_from_status":{"type":["string","null"],"description":"Amazon SES MAIL FROM status (pending/success/failed/temporary_failure/not_started)"},"verified_at":{"type":["string","null"],"description":"ISO 8601 timestamp of last successful verification"},"created_at":{"type":"string","description":"ISO 8601 creation timestamp"},"mailbox_count":{"type":"integer","minimum":0,"description":"Active mailboxes currently using this domain","example":14},"dns_records":{"$ref":"#/components/schemas/MailboxDomainDnsRecords"}},"required":["id","domain","mode","verification_status","ses_identity_verification_status","ses_verified_for_sending","ses_dkim_status","ses_dkim_signing_enabled","ses_identity_checked_at","ses_mail_from_status","verified_at","created_at","mailbox_count","dns_records"],"additionalProperties":false},"DomainItemCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxDomain"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"DomainItemResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxDomain"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxDomainVerifyChecks":{"type":"object","properties":{"mx":{"type":"boolean","description":"MX record present when the domain is configured for receiving. Always true for send-only domains."},"verification_txt":{"type":"boolean","description":"Ownership TXT record present with correct value"},"spf":{"type":"boolean","description":"Published SPF policy is compatible with the required Amazon SES sender authorisation."},"dmarc":{"type":"boolean","description":"A DMARC record containing v=DMARC1 is present."},"mail_from_mx":{"type":"boolean","description":"Custom MAIL FROM MX record matches expected value"},"mail_from_spf":{"type":"boolean","description":"Custom MAIL FROM SPF policy is compatible with the required Amazon SES sender authorisation."}},"required":["mx","verification_txt","spf","dmarc","mail_from_mx","mail_from_spf"],"additionalProperties":false},"MailboxDomainVerifyResult":{"type":"object","properties":{"status":{"type":"string","enum":["verified","pending","failed"],"description":"Post-check verification status"},"ses_identity_verification_status":{"type":"string","description":"Latest Amazon SES identity status"},"ses_verified_for_sending":{"type":"boolean","description":"Whether Amazon SES permits identity sending"},"ses_dkim_status":{"type":"string","description":"Latest Amazon SES DKIM status"},"ses_dkim_signing_enabled":{"type":"boolean","description":"Whether Amazon SES DKIM signing is enabled"},"ses_identity_checked_at":{"type":"string","description":"ISO 8601 time of this SES identity check"},"ses_mail_from_status":{"type":"string","description":"Latest Amazon SES MAIL FROM status"},"checks":{"$ref":"#/components/schemas/MailboxDomainVerifyChecks"}},"required":["status","ses_identity_verification_status","ses_verified_for_sending","ses_dkim_status","ses_dkim_signing_enabled","ses_identity_checked_at","ses_mail_from_status","checks"],"additionalProperties":false},"DomainVerifyResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxDomainVerifyResult"}},"required":["data"]}],"unevaluatedProperties":false},"DomainDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"MailboxSendScope":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["all","providers","group"],"description":"Outbound routing strategy. `all` lets the mailbox use any team-configured provider; `providers` restricts to the listed provider IDs; `group` routes via a delivery group."},"provider_public_ids":{"type":"array","items":{"type":"string"},"description":"Provider public IDs (only when type=providers)"},"group_public_ids":{"type":"array","items":{"type":"string"},"description":"Delivery group public IDs (only when type=group)"}},"required":["type"],"additionalProperties":false},"Mailbox":{"type":"object","properties":{"id":{"type":"string","description":"Public ID","example":"mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"email":{"type":"string","description":"Mailbox email address (lowercase)","example":"agent@acme.com"},"display_name":{"type":["string","null"],"description":"Optional display name shown in outbound From headers"},"quota_bytes":{"type":["integer","null"],"description":"Storage quota in bytes. Current writable tiers are 1 GB, 5 GB, and 50 GB."},"send_scope":{"$ref":"#/components/schemas/MailboxSendScope"},"status":{"type":"string","description":"active | suspended | deleted","example":"active"},"created_at":{"type":"string","description":"ISO 8601 creation timestamp"}},"required":["id","email","display_name","quota_bytes","send_scope","status","created_at"],"additionalProperties":false},"MailboxItemCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxAvailabilityReason":{"type":"string","enum":["available","invalid_email","domain_not_available","taken","reserved","cleanup_pending"]},"MailboxAvailabilityResult":{"type":"object","properties":{"email":{"type":"string","description":"Normalised mailbox email address checked.","example":"agent@myagent.mx"},"available":{"type":"boolean","description":"Whether this address can be reserved for mailbox creation."},"reason":{"$ref":"#/components/schemas/MailboxAvailabilityReason"}},"required":["email","available","reason"],"additionalProperties":false},"MailboxAvailabilityResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxAvailabilityResult"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxCredential":{"type":"object","properties":{"public_id":{"type":"string","description":"Credential public ID","example":"smx_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"secret":{"type":"string","description":"Mailbox credential — shown exactly once. Use as a Bearer token on the HTTP API and as the password for IMAP retrieval and SMTP submission."},"key_prefix":{"type":"string"},"key_suffix":{"type":"string"},"server":{"type":"string","description":"Mailbox server name","example":"mail.qubrics.com"},"imap_port":{"type":"integer","description":"IMAP retrieval port","example":993},"smtp_port":{"type":"integer","description":"SMTP submission port","example":587},"username":{"type":"string","description":"Mailbox email address used as the login"}},"required":["public_id","secret","key_prefix","key_suffix","server","imap_port","smtp_port","username"],"additionalProperties":false},"MailboxCreateResult":{"type":"object","properties":{"mailbox":{"$ref":"#/components/schemas/Mailbox"},"credential":{"anyOf":[{"$ref":"#/components/schemas/MailboxCredential"},{"type":"null"}],"description":"Initial credential for the mailbox. `null` if credential generation failed — call POST /mailboxes/{id}/keys to retry."},"warning":{"type":["string","null"],"description":"Optional warning string when the mailbox was created without an initial credential"}},"required":["mailbox","credential","warning"],"additionalProperties":false},"MailboxCreateResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxCreateResult"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxItemResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/Mailbox"}},"required":["data"]}],"unevaluatedProperties":false},"UpdateMailboxBody":{"type":"object","properties":{"display_name":{"type":["string","null"],"minLength":1,"maxLength":254,"description":"Replace the display name; send null to clear it."},"quota_bytes":{"type":"integer","minimum":1,"description":"Storage quota in bytes. Allowed values: 1073741824 (1 GB), 5368709120 (5 GB), 53687091200 (50 GB).","example":5368709120},"send_scope":{"type":"object","properties":{"type":{"type":"string","enum":["all","providers","group"],"description":"Outbound routing strategy. Use `providers` with provider_public_ids, or `group` with group_public_ids."},"provider_public_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Provider public IDs allowed for sending when type is `providers`."},"group_public_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Delivery group public IDs allowed for sending when type is `group`."}},"required":["type"],"additionalProperties":false,"description":"Replace outbound routing restrictions."}},"additionalProperties":false},"MailboxDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"MailboxAppPasswordResult":{"type":"object","properties":{"credential":{"$ref":"#/components/schemas/MailboxCredential"}},"required":["credential"],"additionalProperties":false},"MailboxAppPasswordResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxAppPasswordResult"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxKeyDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"GrantedMailbox":{"type":"object","properties":{"id":{"type":"string","description":"Mailbox public ID","example":"mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"email":{"type":"string","description":"Mailbox email address","example":"agent@acme.com"}},"required":["id","email"],"additionalProperties":false},"GrantedMailboxListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GrantedMailbox"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxMe":{"type":"object","properties":{"id":{"type":"string","description":"Public ID","example":"mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"email":{"type":"string","description":"Mailbox email address (lowercase)","example":"agent@acme.com"},"display_name":{"type":["string","null"],"description":"Optional display name shown in outbound From headers"},"quota_bytes":{"type":["integer","null"],"description":"Storage quota in bytes. Current writable tiers are 1 GB, 5 GB, and 50 GB."},"send_scope":{"$ref":"#/components/schemas/MailboxSendScope"},"status":{"type":"string","description":"active | suspended | deleted","example":"active"},"created_at":{"type":"string","description":"ISO 8601 creation timestamp"},"quota_used_bytes":{"type":"integer","description":"Live storage usage in bytes. Omitted when usage is temporarily unavailable."}},"required":["id","email","display_name","quota_bytes","send_scope","status","created_at"],"additionalProperties":false},"MailboxMeItemResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxMe"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxCostUsage":{"type":"object","properties":{"mailbox_id":{"type":"string"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"currency":{"type":"string","enum":["USD"]},"state":{"type":"string","enum":["pending","final"]},"posted_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"incoming":{"type":"object","properties":{"quantity":{"type":"string","pattern":"^\\d+$"},"incurred_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"posted_quantity":{"type":"string","pattern":"^\\d+$"},"posted_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"unbillable_quantity":{"type":"string","pattern":"^\\d+$"},"unbillable_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"coverage_started_at":{"type":["string","null"],"format":"date-time"},"state":{"type":"string","enum":["pending","final"]}},"required":["quantity","incurred_amount","posted_quantity","posted_amount","unbillable_quantity","unbillable_amount","coverage_started_at","state"],"additionalProperties":false},"outgoing":{"type":"object","properties":{"quantity":{"type":"string","pattern":"^\\d+$"},"incurred_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"posted_quantity":{"type":"string","pattern":"^\\d+$"},"posted_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"unbillable_quantity":{"type":"string","pattern":"^\\d+$"},"unbillable_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"coverage_started_at":{"type":["string","null"],"format":"date-time"},"state":{"type":"string","enum":["pending","final"]}},"required":["quantity","incurred_amount","posted_quantity","posted_amount","unbillable_quantity","unbillable_amount","coverage_started_at","state"],"additionalProperties":false},"storage":{"type":"object","properties":{"raw_amount":{"type":"string","pattern":"^\\d+\\.\\d{18}$"},"allocated_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"posted_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"state":{"type":"string","enum":["pending","final"]}},"required":["raw_amount","allocated_amount","posted_amount","state"],"additionalProperties":false}},"required":["mailbox_id","start","end","currency","state","posted_amount","incoming","outgoing","storage"],"additionalProperties":false},"MailboxCostUsageResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxCostUsage"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxSession":{"type":"object","properties":{"mailbox":{"type":"object","properties":{"id":{"type":"string","description":"Mailbox public ID","example":"mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"email":{"type":"string","format":"email","example":"agent@example.com"},"display_name":{"type":["string","null"]}},"required":["id","email","display_name"],"additionalProperties":false},"states":{"type":"object","properties":{"messages":{"type":"string"},"folders":{"type":"string"},"threads":{"type":"string"},"submissions":{"type":"string"},"identities":{"type":"string"},"quotas":{"type":"string"}},"required":["messages","folders","threads","submissions","identities","quotas"],"additionalProperties":false},"capabilities":{"type":"object","properties":{"messages":{"type":"object","properties":{"list":{"type":"boolean"},"detail":{"type":"boolean"},"raw_body":{"type":"boolean"},"clean_content":{"type":"boolean"},"batch_get":{"type":"boolean"},"count":{"type":"boolean"},"search_snippets":{"type":"boolean"},"changes":{"type":"boolean"},"query_changes":{"type":"boolean"},"update_fields":{"type":"array","items":{"type":"string","enum":["seen","flagged","keywords"]}},"keywords":{"type":"boolean"},"batch_update":{"type":"boolean"},"delete":{"type":"boolean"},"permanent_delete":{"type":"boolean"}},"required":["list","detail","raw_body","clean_content","batch_get","count","search_snippets","changes","query_changes","update_fields","keywords","batch_update","delete","permanent_delete"],"additionalProperties":false},"threads":{"type":"object","properties":{"list":{"type":"boolean"},"detail":{"type":"boolean"},"messages":{"type":"boolean"},"clean_content":{"type":"boolean"},"changes":{"type":"boolean"}},"required":["list","detail","messages","clean_content","changes"],"additionalProperties":false},"folders":{"type":"object","properties":{"list":{"type":"boolean"},"detail":{"type":"boolean"},"create":{"type":"boolean"},"update":{"type":"boolean"},"delete":{"type":"boolean"},"changes":{"type":"boolean"},"query_changes":{"type":"boolean"}},"required":["list","detail","create","update","delete","changes","query_changes"],"additionalProperties":false},"submissions":{"type":"object","properties":{"list":{"type":"boolean"},"detail":{"type":"boolean"},"changes":{"type":"boolean"},"send":{"type":"boolean"}},"required":["list","detail","changes","send"],"additionalProperties":false},"identities":{"type":"object","properties":{"list":{"type":"boolean"},"changes":{"type":"boolean"},"create":{"type":"boolean"},"update":{"type":"boolean"},"delete":{"type":"boolean"}},"required":["list","changes","create","update","delete"],"additionalProperties":false},"quotas":{"type":"object","properties":{"list":{"type":"boolean"},"usage":{"type":"boolean"},"changes":{"type":"boolean"},"update":{"type":"boolean"}},"required":["list","usage","changes","update"],"additionalProperties":false},"attachments":{"type":"object","properties":{"upload":{"type":"boolean"},"download":{"type":"boolean"},"range_download":{"type":"boolean"},"metadata":{"type":"boolean"},"parsing":{"type":"boolean"},"send_with_uploaded_blob":{"type":"boolean"}},"required":["upload","download","range_download","metadata","parsing","send_with_uploaded_blob"],"additionalProperties":false},"sync":{"type":"object","properties":{"typed_changes":{"type":"boolean"},"types":{"type":"array","items":{"type":"string","enum":["messages","folders","threads","submissions","identities","quotas"]}},"query_changes":{"type":"array","items":{"type":"string","enum":["messages","folders"]}}},"required":["typed_changes","types","query_changes"],"additionalProperties":false}},"required":["messages","threads","folders","submissions","identities","quotas","attachments","sync"],"additionalProperties":false},"limits":{"type":"object","properties":{"draft_schedule_days_max":{"type":"integer","enum":[30]},"list_limit_max":{"type":"integer"},"changes_limit_max":{"type":"integer"},"batch_ids_max":{"type":"integer"},"message_body_chars_default":{"type":"integer"},"thread_body_chars_default":{"type":"integer"},"body_chars_max":{"type":"integer"},"inline_attachment_bytes_max":{"type":"integer"},"attachment_upload_bytes_max":{"type":"integer"},"outbound_raw_message_bytes_max":{"type":"integer"},"keywords_per_update_max":{"type":"integer"}},"required":["draft_schedule_days_max","list_limit_max","changes_limit_max","batch_ids_max","message_body_chars_default","thread_body_chars_default","body_chars_max","inline_attachment_bytes_max","attachment_upload_bytes_max","outbound_raw_message_bytes_max","keywords_per_update_max"],"additionalProperties":false},"gated":{"type":"object","properties":{"identity_mutation":{"type":"boolean"},"quota_mutation":{"type":"boolean"},"vacation_response":{"type":"boolean"},"filter_script_writes":{"type":"boolean"},"events":{"type":"boolean"},"raw_protocol":{"type":"boolean"},"attachment_parsing":{"type":"boolean"},"message_copy":{"type":"boolean"},"message_import":{"type":"boolean"},"message_parse":{"type":"boolean"},"blob_lookup":{"type":"boolean"},"blob_copy":{"type":"boolean"}},"required":["identity_mutation","quota_mutation","vacation_response","filter_script_writes","events","raw_protocol","attachment_parsing","message_copy","message_import","message_parse","blob_lookup","blob_copy"],"additionalProperties":false,"description":"Flags are true when a feature is intentionally unavailable through the mailbox API."},"endpoints":{"type":"object","properties":{"mailbox":{"type":"array","items":{"type":"string"}},"messages":{"type":"array","items":{"type":"string"}},"threads":{"type":"array","items":{"type":"string"}},"folders":{"type":"array","items":{"type":"string"}},"submissions":{"type":"array","items":{"type":"string"}},"usage":{"type":"array","items":{"type":"string"}},"sync":{"type":"array","items":{"type":"string"}}},"required":["mailbox","messages","threads","folders","submissions","usage","sync"],"additionalProperties":false}},"required":["mailbox","states","capabilities","limits","gated","endpoints"],"additionalProperties":false},"MailboxSessionResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxSession"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxAddress":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"agent@example.com"},"name":{"type":["string","null"],"example":"Support"}},"required":["email","name"],"additionalProperties":false},"MailboxIdentity":{"type":"object","properties":{"id":{"type":"string","description":"Identity ID"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"reply_to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"bcc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"text_signature":{"type":"string"},"html_signature":{"type":"string"},"may_delete":{"type":"boolean","description":"Whether the mailbox service allows this identity to be deleted."}},"required":["id","name","email","reply_to","bcc","text_signature","html_signature","may_delete"],"additionalProperties":false},"MailboxIdentityResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxIdentity"}},"required":["data"]}],"unevaluatedProperties":false},"UpdateMailboxIdentityBody":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":254,"description":"Default sender name. Send null or an empty string to clear it."},"text_signature":{"type":["string","null"],"maxLength":2047,"description":"Plain text signature appended to Mailbox API sends that include text_body."},"html_signature":{"type":["string","null"],"maxLength":2047,"description":"HTML signature appended to Mailbox API sends that include html_body."}},"additionalProperties":false},"MailboxIdentityListMeta":{"type":"object","properties":{"request_id":{"type":"string"},"identity_state":{"type":"string"}},"required":["request_id"],"additionalProperties":false},"MailboxIdentityCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/MailboxIdentityListMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxIdentity"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxQueryMeta":{"type":"object","properties":{"request_id":{"type":"string"},"query_state":{"type":"string"}},"required":["request_id"],"additionalProperties":false},"MailboxSubmissionEnvelopeAddress":{"type":"object","properties":{"email":{"type":"string","format":"email"},"parameters":{"type":["object","null"],"additionalProperties":{"type":["string","null"]}}},"required":["email","parameters"],"additionalProperties":false},"MailboxSubmissionEnvelope":{"type":["object","null"],"properties":{"mail_from":{"anyOf":[{"$ref":"#/components/schemas/MailboxSubmissionEnvelopeAddress"},{"type":"null"}]},"rcpt_to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxSubmissionEnvelopeAddress"}}},"required":["mail_from","rcpt_to"],"additionalProperties":false},"MailboxSubmissionDeliveryStatus":{"type":"object","properties":{"email":{"type":"string","format":"email"},"smtp_reply":{"type":["string","null"]},"delivered":{"type":["string","null"]},"displayed":{"type":["string","null"]}},"required":["email","smtp_reply","delivered","displayed"],"additionalProperties":false},"MailboxSubmission":{"type":"object","properties":{"id":{"type":"string","description":"Submission ID"},"identity_id":{"type":["string","null"]},"email_id":{"type":["string","null"]},"thread_id":{"type":["string","null"]},"send_at":{"type":["string","null"]},"undo_status":{"type":["string","null"]},"envelope":{"$ref":"#/components/schemas/MailboxSubmissionEnvelope"},"delivery_status":{"type":"array","items":{"$ref":"#/components/schemas/MailboxSubmissionDeliveryStatus"}},"dsn_blob_ids":{"type":"array","items":{"type":"string"}},"mdn_blob_ids":{"type":"array","items":{"type":"string"}}},"required":["id","identity_id","email_id","thread_id","send_at","undo_status","envelope","delivery_status","dsn_blob_ids","mdn_blob_ids"],"additionalProperties":false},"MailboxSubmissionCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/MailboxQueryMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxSubmission"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxChanges":{"type":"object","properties":{"old_state":{"type":["string","null"]},"new_state":{"type":"string"},"has_more":{"type":"boolean"},"created":{"type":"array","items":{"type":"string"}},"updated":{"type":"array","items":{"type":"string"}},"destroyed":{"type":"array","items":{"type":"string"}},"updated_properties":{"type":"array","items":{"type":"string"}},"sync_required":{"type":"boolean","description":"When true, refetch this resource list instead of applying the incremental arrays."}},"required":["old_state","new_state","has_more","created","updated","destroyed"],"additionalProperties":false},"MailboxChangesResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxChanges"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxSubmissionResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxSubmission"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxQuota":{"type":"object","properties":{"id":{"type":"string","description":"Quota ID"},"resource_type":{"type":"string","example":"octets"},"used":{"type":"integer"},"hard_limit":{"type":"integer"},"warn_limit":{"type":["integer","null"]},"soft_limit":{"type":["integer","null"]},"scope":{"type":"string","example":"account"},"name":{"type":"string"},"types":{"type":"array","items":{"type":"string"}},"description":{"type":["string","null"]}},"required":["id","resource_type","used","hard_limit","warn_limit","soft_limit","scope","name","types","description"],"additionalProperties":false},"MailboxQuotaCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/MailboxQueryMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxQuota"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxUsageResource":{"type":"object","properties":{"quota_id":{"type":"string"},"name":{"type":"string"},"resource_type":{"type":"string"},"scope":{"type":"string"},"types":{"type":"array","items":{"type":"string"}},"used":{"type":"integer"},"hard_limit":{"type":"integer"},"warn_limit":{"type":["integer","null"]},"soft_limit":{"type":["integer","null"]},"percent_used":{"type":["number","null"]},"limit_status":{"type":"string","enum":["ok","warning","soft_limit","hard_limit","unknown"]}},"required":["quota_id","name","resource_type","scope","types","used","hard_limit","warn_limit","soft_limit","percent_used","limit_status"],"additionalProperties":false},"MailboxUsage":{"type":"object","properties":{"resources":{"type":"array","items":{"$ref":"#/components/schemas/MailboxUsageResource"}},"states":{"type":"object","properties":{"quota_state":{"type":["string","null"]}},"required":["quota_state"],"additionalProperties":false}},"required":["resources","states"],"additionalProperties":false},"MailboxUsageResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxUsage"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxSyncMeta":{"type":"object","properties":{"request_id":{"type":"string"},"sync_state":{"type":"string"}},"required":["request_id"],"additionalProperties":false},"MailboxAttachment":{"type":"object","properties":{"id":{"type":"string","description":"Attachment blob ID."},"filename":{"type":["string","null"],"example":"invoice.pdf"},"content_type":{"type":"string","example":"application/pdf"},"size_bytes":{"type":["integer","null"],"example":12345},"disposition":{"type":["string","null"],"example":"attachment"},"content_id":{"type":["string","null"],"description":"Content ID for inline attachments, when present."},"download_url":{"type":"string","description":"Short-lived URL for this exact attachment. Fetch it promptly; if it expires, call the message or attachment metadata endpoint again to receive a fresh URL.","example":"https://app.qubrics.com/api/v1/mailbox/messages/msg_123/attachment-downloads/attref_abc123?download_token=..."}},"required":["id","filename","content_type","size_bytes","disposition","content_id"],"additionalProperties":false},"MailboxMessageFlags":{"type":"object","properties":{"seen":{"type":"boolean"},"flagged":{"type":"boolean"},"draft":{"type":"boolean"},"answered":{"type":"boolean"}},"required":["seen","flagged","draft","answered"],"additionalProperties":false},"MailboxMessageSummary":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"thread_id":{"type":["string","null"]},"folder_ids":{"type":"array","items":{"type":"string"}},"subject":{"type":["string","null"]},"preview":{"type":["string","null"]},"from":{"anyOf":[{"$ref":"#/components/schemas/MailboxAddress"},{"type":"null"}]},"to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"cc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"bcc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"received_at":{"type":["string","null"]},"sent_at":{"type":["string","null"]},"size_bytes":{"type":["integer","null"]},"has_attachments":{"type":"boolean"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAttachment"},"description":"Attachment metadata for this message. Each item includes a short-lived `download_url`; if it expires, fetch message metadata again."},"keywords":{"type":"array","items":{"type":"string"},"description":"Active message keywords, including system flags and custom labels.","example":["$seen","$flagged","agent_triaged"]},"flags":{"$ref":"#/components/schemas/MailboxMessageFlags"}},"required":["id","thread_id","folder_ids","subject","preview","from","to","cc","bcc","received_at","sent_at","size_bytes","has_attachments","keywords","flags"],"additionalProperties":false},"MailboxMessageSummaryCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/MailboxSyncMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxMessageSummary"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxMessageQueryChanges":{"type":"object","properties":{"old_query_state":{"type":["string","null"]},"new_query_state":{"type":"string"},"has_more":{"type":"boolean"},"removed":{"type":"array","items":{"type":"string"}},"added":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"index":{"type":"integer"}},"required":["id","index"],"additionalProperties":false}},"total":{"type":["integer","null"]}},"required":["old_query_state","new_query_state","has_more","removed","added","total"],"additionalProperties":false},"MailboxMessageQueryChangesResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxMessageQueryChanges"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxRawBody":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"thread_id":{"type":["string","null"]},"part":{"type":"string","enum":["text","html","both"]},"body":{"type":"object","properties":{"text":{"type":["string","null"]},"html":{"type":["string","null"]},"is_truncated":{"type":"boolean"},"truncated_at_chars":{"type":["integer","null"]}},"required":["text","html","is_truncated","truncated_at_chars"],"additionalProperties":false},"states":{"type":"object","properties":{"email_state":{"type":["string","null"]}},"required":["email_state"],"additionalProperties":false}},"required":["id","thread_id","part","body","states"],"additionalProperties":false},"MailboxContentHeaders":{"type":"object","properties":{"mode":{"type":"string","enum":["none","selected","full"]},"selected":{"type":["object","null"],"properties":{"message_id":{"type":"array","items":{"type":"string"}},"in_reply_to":{"type":["string","null"]},"references":{"type":"array","items":{"type":"string"}},"reply_to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}}},"required":["message_id","in_reply_to","references","reply_to"]},"full":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"],"additionalProperties":false}}},"required":["mode","selected","full"],"additionalProperties":false},"MailboxMessageContent":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"thread_id":{"type":["string","null"]},"subject":{"type":["string","null"]},"participants":{"type":"object","properties":{"from":{"anyOf":[{"$ref":"#/components/schemas/MailboxAddress"},{"type":"null"}]},"to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"cc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"bcc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"reply_to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}}},"required":["from","to","cc","bcc","reply_to"],"additionalProperties":false},"dates":{"type":"object","properties":{"received_at":{"type":["string","null"]},"sent_at":{"type":["string","null"]}},"required":["received_at","sent_at"],"additionalProperties":false},"body":{"type":"object","properties":{"format":{"type":["string","null"],"enum":["text","html"]},"text":{"type":["string","null"]},"html":{"type":["string","null"],"description":"HTML body when requested. Returned as a JSON string and not as rendered content."},"cleaned_html":{"type":["string","null"],"description":"HTML with recognised quotes and signatures removed according to the stripping options. Original HTML remains in html. This is not sanitised content. Null when HTML is absent, not requested, truncated, or exceeds cleaning limits."},"html_cleaning":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["complete","source_truncated","limit_exceeded"]},"signature_stripped":{"type":"boolean"},"quotes_stripped":{"type":"boolean"}},"required":["status","signature_stripped","quotes_stripped"],"additionalProperties":false,"description":"HTML cleaning outcome; null when HTML is absent or not requested. Cleaning accepts at most 20,000 elements and 128 nested elements. Unrecognised quote and signature formats remain unchanged."},"is_truncated":{"type":"boolean"},"truncated_at_chars":{"type":["integer","null"]},"signature_stripped":{"type":"boolean"},"quotes_stripped":{"type":"boolean"},"extracted_links":{"type":"array","items":{"type":"string"}}},"required":["format","text","html","cleaned_html","html_cleaning","is_truncated","truncated_at_chars","signature_stripped","quotes_stripped","extracted_links"],"additionalProperties":false},"headers":{"$ref":"#/components/schemas/MailboxContentHeaders"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAttachment"},"description":"Attachment metadata only. Attachment contents are not parsed by this endpoint."},"states":{"type":"object","properties":{"email_state":{"type":["string","null"]},"option_hash":{"type":"string"}},"required":["email_state","option_hash"],"additionalProperties":false}},"required":["id","thread_id","subject","participants","dates","body","headers","attachments","states"],"additionalProperties":false},"MailboxBatchGetItem":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/MailboxMessageSummary"},"raw_body":{"anyOf":[{"$ref":"#/components/schemas/MailboxRawBody"},{"type":"null"}]},"content":{"anyOf":[{"$ref":"#/components/schemas/MailboxMessageContent"},{"type":"null"}]}},"required":["message","raw_body","content"],"additionalProperties":false},"MailboxBatchGetResult":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/MailboxBatchGetItem"}},"not_found":{"type":"array","items":{"type":"string"}},"states":{"type":"object","properties":{"email_state":{"type":["string","null"]}},"required":["email_state"],"additionalProperties":false}},"required":["messages","not_found","states"],"additionalProperties":false},"MailboxBatchGetResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxBatchGetResult"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxBatchGetBody":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"Message IDs to fetch, maximum 100."},"body_mode":{"type":"string","enum":["none","raw","clean_json"],"description":"Body shape to include for each message."},"part":{"type":"string","enum":["auto","text","html","both"],"description":"Body part to return when body_mode is not `none`."},"max_body_chars":{"type":"integer","minimum":1,"maximum":1000000,"description":"Maximum body characters per message before truncation."},"strip_signature":{"type":"boolean","description":"When true, remove detected email signatures."},"strip_quotes":{"type":"boolean","description":"When true, remove quoted reply text."},"include_links":{"type":"boolean","description":"When true, include links extracted from the body."},"include_html":{"type":"boolean","description":"When true, include HTML content when available."},"include_headers":{"type":"string","enum":["none","selected","full"],"description":"Header detail to include in each message."},"include_attachments":{"type":"string","enum":["none","metadata"],"description":"Attachment detail to include. Contents are not returned."}},"required":["ids"],"additionalProperties":false},"MailboxBatchMessageFailure":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["id","code","message"],"additionalProperties":false},"MailboxBatchMessageStates":{"type":"object","properties":{"old_state":{"type":["string","null"]},"new_state":{"type":["string","null"]}},"required":["old_state","new_state"],"additionalProperties":false},"MailboxBatchUpdateMessagesResult":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"string"}},"not_found":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/MailboxBatchMessageFailure"}},"states":{"$ref":"#/components/schemas/MailboxBatchMessageStates"}},"required":["updated","not_found","failed","states"],"additionalProperties":false},"MailboxBatchUpdateMessagesResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxBatchUpdateMessagesResult"}},"required":["data"]}],"unevaluatedProperties":false},"BatchUpdateMailboxMessagesBody":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"Message IDs to update, maximum 100."},"seen":{"type":"boolean","description":"Set or clear the seen flag."},"flagged":{"type":"boolean","description":"Set or clear the flagged marker."},"keywords":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Map of message keyword names to booleans. `true` sets the keyword; `false` clears it. Keyword names are normalised to lowercase. Lifecycle keywords such as `$draft` are read-only.","example":{"$answered":true,"agent_triaged":true,"needs_reply":false}},"if_in_state":{"type":"string","description":"Optional message state token for stale-write protection."}},"required":["ids"],"additionalProperties":false},"MailboxBatchDeleteMessagesResult":{"type":"object","properties":{"deleted":{"type":"array","items":{"type":"string"}},"not_found":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/MailboxBatchMessageFailure"}},"states":{"$ref":"#/components/schemas/MailboxBatchMessageStates"}},"required":["deleted","not_found","failed","states"],"additionalProperties":false},"MailboxBatchDeleteMessagesResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxBatchDeleteMessagesResult"}},"required":["data"]}],"unevaluatedProperties":false},"BatchDeleteMailboxMessagesBody":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"Message IDs to delete, maximum 100."},"permanent":{"type":"boolean","description":"When true, permanently deletes instead of moving to Trash."},"if_in_state":{"type":"string","description":"Optional message state token for stale-write protection."}},"required":["ids"],"additionalProperties":false},"MailboxMessageCount":{"type":"object","properties":{"total":{"type":"integer"},"sync_state":{"type":["string","null"]}},"required":["total","sync_state"],"additionalProperties":false},"MailboxMessageCountResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxMessageCount"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxSearchSnippet":{"type":"object","properties":{"message_id":{"type":"string"},"subject":{"type":["string","null"],"description":"Subject snippet. May include mark tags."},"preview":{"type":["string","null"],"description":"Body preview snippet. May include mark tags."}},"required":["message_id","subject","preview"],"additionalProperties":false},"MailboxSearchSnippetsResult":{"type":"object","properties":{"snippets":{"type":"array","items":{"$ref":"#/components/schemas/MailboxSearchSnippet"}},"not_found":{"type":"array","items":{"type":"string"}},"sync_state":{"type":["string","null"]}},"required":["snippets","not_found","sync_state"],"additionalProperties":false},"MailboxSearchSnippetsResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxSearchSnippetsResult"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxAttachmentUploadResult":{"type":"object","properties":{"blob_id":{"type":"string","description":"Uploaded attachment blob ID for a later send request."},"filename":{"type":"string","example":"invoice.pdf"},"content_type":{"type":"string","example":"application/pdf"},"size_bytes":{"type":"integer","example":12345}},"required":["blob_id","filename","content_type","size_bytes"],"additionalProperties":false},"MailboxAttachmentUploadResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxAttachmentUploadResult"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxAttachmentUploadIntentResult":{"type":"object","properties":{"upload_id":{"type":"string","description":"Short-lived upload intent ID."},"upload_url":{"type":"string","description":"Short-lived signed PUT URL for this exact attachment. Upload promptly; if it expires, create a new upload URL.","example":"https://app.qubrics.com/api/v1/mailbox/attachment-uploads/upl_123?upload_token=..."},"method":{"type":"string","enum":["PUT"],"description":"HTTP method to use with `upload_url`."},"expires_at":{"type":"string","format":"date-time","description":"Upload URL expiry time."},"headers":{"type":"object","properties":{"Content-Type":{"type":"string"},"Content-Length":{"type":"string"}},"required":["Content-Type","Content-Length"],"additionalProperties":false,"description":"Headers that must be sent exactly with the PUT request."},"max_size_bytes":{"type":"integer","description":"Maximum accepted attachment size in bytes."}},"required":["upload_id","upload_url","method","expires_at","headers","max_size_bytes"],"additionalProperties":false},"MailboxAttachmentUploadIntentResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxAttachmentUploadIntentResult"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxAttachmentUploadIntentBody":{"type":"object","properties":{"filename":{"type":"string","description":"Filename to use when sending the uploaded attachment."},"content_type":{"type":"string","description":"Content-Type that must be sent on the later PUT request.","example":"application/pdf"},"size_bytes":{"type":"integer","minimum":1,"description":"Exact byte length that must be sent on the later PUT request."}},"required":["filename","content_type","size_bytes"],"additionalProperties":false},"SendMailboxMessageResult":{"type":"object","properties":{"message_id":{"type":"string"},"status":{"type":"string","enum":["queued"]}},"required":["message_id","status"],"additionalProperties":false},"MailboxSendResultResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SendMailboxMessageResult"}},"required":["data"]}],"unevaluatedProperties":false},"SendMailboxMessageBody":{"type":"object","properties":{"from":{"allOf":[{"$ref":"#/components/schemas/MailboxAddress"},{"description":"Sender address. Defaults to mailbox identity."}]},"to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"},"maxItems":50,"description":"Primary recipients. Supply 1 to 50 recipients in total across To, Cc and Bcc."},"cc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"},"maxItems":50,"description":"Visible copied recipients."},"bcc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"},"maxItems":50,"description":"Hidden copied recipients."},"reply_to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"},"description":"Reply-To recipients."},"subject":{"type":"string","maxLength":998,"description":"Subject line; defaults to empty."},"text_body":{"type":"string","description":"Plain text body."},"html_body":{"type":"string","description":"HTML body."},"custom_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom X-* headers to include. Mailbox writes reject X-SES-TENANT, X-SES-CONFIGURATION-SET and X-SES-MESSAGE-TAGS case-insensitively."},"attachments":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"content":{"type":"string","description":"Base64-encoded content for small inline attachments. Use /mailbox/attachments:upload for larger files."}},"required":["filename","content_type","content"],"additionalProperties":false},{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"blob_id":{"type":"string","description":"Blob ID returned by /mailbox/attachments:upload."}},"required":["filename","content_type","blob_id"],"additionalProperties":false}]},"description":"Attachments to send with the message."}},"additionalProperties":false},"MailboxMessage":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"thread_id":{"type":["string","null"]},"folder_ids":{"type":"array","items":{"type":"string"}},"subject":{"type":["string","null"]},"preview":{"type":["string","null"]},"from":{"anyOf":[{"$ref":"#/components/schemas/MailboxAddress"},{"type":"null"}]},"to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"cc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"bcc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"received_at":{"type":["string","null"]},"sent_at":{"type":["string","null"]},"size_bytes":{"type":["integer","null"]},"has_attachments":{"type":"boolean"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAttachment"},"description":"Attachment metadata for this message. Each item includes a short-lived `download_url`; if it expires, fetch message metadata again."},"keywords":{"type":"array","items":{"type":"string"},"description":"Active message keywords, including system flags and custom labels.","example":["$seen","$flagged","agent_triaged"]},"flags":{"$ref":"#/components/schemas/MailboxMessageFlags"},"text_body":{"type":["string","null"]},"html_body":{"type":["string","null"]},"message_id":{"type":"array","items":{"type":"string"},"description":"`Message-ID` header values for this message, with the surrounding angle brackets removed. Empty when the message carries no `Message-ID`.","example":["20260919.0001@example.com"]},"in_reply_to":{"type":"array","items":{"type":"string"},"description":"`In-Reply-To` header values, with the surrounding angle brackets removed — the message this one replies to. Empty when the message is not a reply.","example":["20260918.0009@example.com"]},"references":{"type":"array","items":{"type":"string"},"description":"`References` header values, with the surrounding angle brackets removed — the ancestor chain of this message, oldest first. Empty when the message starts a conversation.","example":["20260917.0001@example.com","20260918.0009@example.com"]},"reply_to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"},"description":"`Reply-To` addresses. Address replies here rather than to `from` whenever this is non-empty. Empty when the message carries no `Reply-To`."}},"required":["id","thread_id","folder_ids","subject","preview","from","to","cc","bcc","received_at","sent_at","size_bytes","has_attachments","keywords","flags","text_body","html_body","message_id","in_reply_to","references","reply_to"],"additionalProperties":false},"MailboxMessageDetailResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxMessage"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxRawBodyResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxRawBody"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxMessageContentResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxMessageContent"}},"required":["data"]}],"unevaluatedProperties":false},"PatchMailboxMessageBody":{"type":"object","properties":{"seen":{"type":"boolean"},"flagged":{"type":"boolean"},"keywords":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Map of message keyword names to booleans. `true` sets the keyword; `false` clears it. Keyword names are normalised to lowercase. Lifecycle keywords such as `$draft` are read-only.","example":{"$answered":true,"agent_triaged":true,"needs_reply":false}}},"additionalProperties":false},"MailboxMessageDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"MailboxThreadSummary":{"type":"object","properties":{"id":{"type":"string","description":"Thread ID"},"subject":{"type":["string","null"]},"message_count":{"type":"integer"},"unread_count":{"type":"integer"},"has_attachments":{"type":"boolean"},"folder_ids":{"type":"array","items":{"type":"string"}},"participants":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"last_message":{"anyOf":[{"$ref":"#/components/schemas/MailboxMessageSummary"},{"type":"null"}]},"states":{"type":"object","properties":{"thread_state":{"type":["string","null"]},"email_state":{"type":["string","null"]}},"required":["thread_state","email_state"],"additionalProperties":false}},"required":["id","subject","message_count","unread_count","has_attachments","folder_ids","participants","last_message","states"],"additionalProperties":false},"MailboxThreadSummaryCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/MailboxQueryMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxThreadSummary"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxThread":{"type":"object","properties":{"id":{"type":"string","description":"Thread ID"},"subject":{"type":["string","null"]},"message_count":{"type":"integer"},"unread_count":{"type":"integer"},"has_attachments":{"type":"boolean"},"folder_ids":{"type":"array","items":{"type":"string"}},"participants":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"last_message":{"anyOf":[{"$ref":"#/components/schemas/MailboxMessageSummary"},{"type":"null"}]},"states":{"type":"object","properties":{"thread_state":{"type":["string","null"]},"email_state":{"type":["string","null"]}},"required":["thread_state","email_state"],"additionalProperties":false},"message_ids":{"type":"array","items":{"type":"string"}}},"required":["id","subject","message_count","unread_count","has_attachments","folder_ids","participants","last_message","states","message_ids"],"additionalProperties":false},"MailboxThreadDetailResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxThread"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxThreadMessagesMeta":{"type":"object","properties":{"request_id":{"type":"string"},"thread_id":{"type":"string"},"sync_state":{"type":"string"}},"required":["request_id","thread_id"],"additionalProperties":false},"MailboxThreadMessageSummaryCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/MailboxThreadMessagesMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxMessageSummary"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxThreadContentMeta":{"type":"object","properties":{"request_id":{"type":"string"},"thread_id":{"type":"string"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"states":{"type":"object","properties":{"thread_state":{"type":["string","null"]},"email_state":{"type":["string","null"]},"option_hash":{"type":"string"}},"required":["thread_state","email_state","option_hash"],"additionalProperties":false}},"required":["request_id","thread_id","participants","states"],"additionalProperties":false},"MailboxThreadContentResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/MailboxThreadContentMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxMessageContent"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxFolder":{"type":"object","properties":{"id":{"type":"string","description":"Folder ID"},"name":{"type":"string"},"parent_id":{"type":["string","null"]},"role":{"type":["string","null"],"description":"System role when the folder is a built-in folder."},"sort_order":{"type":["integer","null"]},"total_messages":{"type":"integer"},"unread_messages":{"type":"integer"},"can_add_items":{"type":"boolean","description":"Whether messages can be moved into this folder."}},"required":["id","name","parent_id","role","sort_order","total_messages","unread_messages","can_add_items"],"additionalProperties":false},"MailboxFolderCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxFolder"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxFolderResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxFolder"}},"required":["data"]}],"unevaluatedProperties":false},"CreateMailboxFolderBody":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":["string","null"]},"sort_order":{"type":"integer"}},"required":["name"],"additionalProperties":false},"MailboxFolderQueryChanges":{"type":"object","properties":{"old_query_state":{"type":["string","null"]},"new_query_state":{"type":"string"},"has_more":{"type":"boolean"},"removed":{"type":"array","items":{"type":"string"}},"added":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"index":{"type":"integer"}},"required":["id","index"],"additionalProperties":false}},"total":{"type":["integer","null"]}},"required":["old_query_state","new_query_state","has_more","removed","added","total"],"additionalProperties":false},"MailboxFolderQueryChangesResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxFolderQueryChanges"}},"required":["data"]}],"unevaluatedProperties":false},"PatchMailboxFolderBody":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":["string","null"]},"sort_order":{"type":"integer"}},"additionalProperties":false},"MailboxFolderDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"MailboxTypedChanges":{"type":"object","properties":{"types":{"type":"object","properties":{"messages":{"$ref":"#/components/schemas/MailboxChanges"},"folders":{"$ref":"#/components/schemas/MailboxChanges"},"threads":{"$ref":"#/components/schemas/MailboxChanges"},"submissions":{"$ref":"#/components/schemas/MailboxChanges"},"identities":{"$ref":"#/components/schemas/MailboxChanges"},"quotas":{"$ref":"#/components/schemas/MailboxChanges"}},"additionalProperties":false}},"required":["types"],"additionalProperties":false},"MailboxTypedChangesResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxTypedChanges"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxRealtimeMessage":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Message ID"},"thread_id":{"type":["string","null"]},"folder_ids":{"type":"array","items":{"type":"string"}},"subject":{"type":["string","null"]},"preview":{"type":["string","null"]},"from":{"anyOf":[{"$ref":"#/components/schemas/MailboxAddress"},{"type":"null"}]},"to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"cc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"bcc":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"}},"received_at":{"type":["string","null"]},"sent_at":{"type":["string","null"]},"size_bytes":{"type":["integer","null"]},"has_attachments":{"type":"boolean"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAttachment"},"description":"Attachment metadata for this message. Each item includes a short-lived `download_url`; if it expires, fetch message metadata again."},"keywords":{"type":"array","items":{"type":"string"},"description":"Active message keywords, including system flags and custom labels.","example":["$seen","$flagged","agent_triaged"]},"flags":{"$ref":"#/components/schemas/MailboxMessageFlags"},"rfc5322_message_id":{"type":["string","null"]},"body":{"type":"object","properties":{"text":{"type":["string","null"]},"html":{"type":["string","null"]},"is_truncated":{"type":"boolean"},"max_bytes":{"type":"integer"}},"required":["text","html","is_truncated","max_bytes"],"additionalProperties":false}},"required":["id","thread_id","folder_ids","subject","preview","from","to","cc","bcc","received_at","sent_at","size_bytes","has_attachments","keywords","flags","rfc5322_message_id","body"],"additionalProperties":false},"MailboxRealtimeEvent":{"type":"object","properties":{"event_type":{"type":"string","enum":["message.received","message.received.spam","sync_required"]},"team_public_id":{"type":"string"},"mailbox_id":{"type":"string"},"message_id":{"type":["string","null"]},"message_id_kind":{"type":["string","null"],"enum":["provider","rfc5322"]},"sender":{"type":["string","null"]},"recipients":{"type":"array","items":{"type":"string"}},"is_spam":{"type":["boolean","null"]},"message":{"$ref":"#/components/schemas/MailboxRealtimeMessage"},"occurred_at":{"type":"string"}},"required":["event_type","team_public_id","mailbox_id","message_id","message_id_kind","sender","recipients","is_spam","message","occurred_at"],"additionalProperties":false},"MailboxCalendar":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"mailbox_id":{"type":"string"},"name":{"type":"string"},"time_zone":{"type":["string","null"]},"is_default":{"type":"boolean","description":"Whether this is the mailbox's current default calendar."}},"required":["id","mailbox_id","name","time_zone","is_default"],"additionalProperties":false},"MailboxCalendarListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxCalendar"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxCalendarCreated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"mailbox_id":{"type":"string"},"name":{"type":"string"},"time_zone":{"type":["string","null"]}},"required":["id","mailbox_id","name","time_zone"],"additionalProperties":false},"MailboxCalendarCreatedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxCalendarCreated"}},"required":["data"]}],"unevaluatedProperties":false},"CreateCalendarBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Private calendar name.","example":"Appointments"},"time_zone":{"type":"string","minLength":1,"maxLength":100,"description":"Time zone for local event times.","example":"Australia/Melbourne"}},"required":["name","time_zone"],"additionalProperties":false},"MailboxCalendarWithEtag":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"mailbox_id":{"type":"string"},"name":{"type":"string"},"time_zone":{"type":["string","null"]},"is_default":{"type":"boolean","description":"Whether this is the mailbox's current default calendar."},"etag":{"type":"string","description":"Current calendar version, matching the ETag response header. Use this value in If-Match to delete an empty calendar."}},"required":["id","mailbox_id","name","time_zone","is_default","etag"],"additionalProperties":false},"MailboxCalendarResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxCalendarWithEtag"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxCalendarDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"MailboxCalendarEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"mailbox_id":{"type":"string"},"calendar_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"maxItems":250},"uid":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"start":{"type":"string"},"time_zone":{"type":["string","null"]},"duration":{"type":"string"}},"required":["id","mailbox_id","calendar_ids","uid","title","description","start","time_zone","duration"],"additionalProperties":false},"MailboxCalendarEventListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxCalendarEvent"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxCalendarEventCreated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"mailbox_id":{"type":"string"},"uid":{"type":"string"}},"required":["id","mailbox_id","uid"],"additionalProperties":false},"MailboxCalendarEventCreatedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxCalendarEventCreated"}},"required":["data"]}],"unevaluatedProperties":false},"CreateCalendarEventBody":{"type":"object","properties":{"calendar_id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Calendar ID in the selected mailbox."},"uid":{"type":"string","minLength":1,"maxLength":255,"description":"Stable caller-held identity, retained before this request. An uncertain create must be reconciled by UID lookup; never repeat it after an empty immediate lookup."},"title":{"type":"string","maxLength":1000,"description":"Event title.","example":"Appointment"},"description":{"type":["string","null"],"maxLength":20000,"description":"Plain text event details. Set null to clear."},"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$","description":"Local start date and time without an offset, interpreted in time_zone.","example":"2026-11-02T10:00:00"},"time_zone":{"type":"string","minLength":1,"maxLength":100,"description":"Time zone for local event times.","example":"Australia/Melbourne"},"duration":{"type":"string","maxLength":80,"pattern":"^P(?=\\d+D|T\\d)(?:\\d+D)?(?:T(?=\\d)(?:\\d+H)?(?:\\d+M)?(?:\\d+(?:\\.\\d{1,9})?S)?)?$","description":"Event duration expressed as days, hours, minutes or seconds.","example":"PT1H"}},"required":["calendar_id","uid","title","start","time_zone","duration"],"additionalProperties":false},"MailboxCalendarEventWithEtag":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"mailbox_id":{"type":"string"},"calendar_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"maxItems":250},"uid":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"start":{"type":"string"},"time_zone":{"type":["string","null"]},"duration":{"type":"string"},"etag":{"type":"string","description":"Current event version, also returned in the ETag response header. Pass this value in If-Match when updating or deleting the event."}},"required":["id","mailbox_id","calendar_ids","uid","title","description","start","time_zone","duration","etag"],"additionalProperties":false},"MailboxCalendarEventResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxCalendarEventWithEtag"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxCalendarEventUpdatedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"updated":{"type":"boolean","enum":[true]}},"required":["id","updated"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"PatchCalendarEventBody":{"type":"object","properties":{"title":{"type":"string","maxLength":1000,"description":"Event title.","example":"Appointment"},"description":{"type":["string","null"],"maxLength":20000,"description":"Plain text event details. Set null to clear."},"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$","description":"Local start date and time without an offset, interpreted in time_zone.","example":"2026-11-02T10:00:00"},"time_zone":{"type":"string","minLength":1,"maxLength":100,"description":"Time zone for local event times.","example":"Australia/Melbourne"},"duration":{"type":"string","maxLength":80,"pattern":"^P(?=\\d+D|T\\d)(?:\\d+D)?(?:T(?=\\d)(?:\\d+H)?(?:\\d+M)?(?:\\d+(?:\\.\\d{1,9})?S)?)?$","description":"Event duration expressed as days, hours, minutes or seconds.","example":"PT1H"}},"additionalProperties":false},"MailboxCalendarEventDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"MailboxCalendarChanges":{"type":"object","properties":{"mailbox_id":{"type":"string"},"resource":{"type":"string","enum":["event"]},"created":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"maxItems":100},"updated":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"maxItems":100},"destroyed":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"maxItems":100},"old_state":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"new_state":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"has_more":{"type":"boolean"},"sync_required":{"type":"boolean"}},"required":["mailbox_id","resource","created","updated","destroyed","old_state","new_state","has_more","sync_required"],"additionalProperties":false},"MailboxCalendarChangesResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxCalendarChanges"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxDraft":{"type":"object","properties":{"from":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false,"description":"Authorised sender; defaults to this inbox."},"to":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Primary recipients; at most 50 total across To, Cc and Bcc."},"cc":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Visible copied recipients."},"bcc":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Hidden copied recipients."},"reply_to":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":20,"description":"Authorised reply addresses; defaults to this inbox."},"subject":{"type":"string","maxLength":998,"description":"Subject; may be empty."},"text_body":{"type":"string","maxLength":1000000,"description":"Plain-text body."},"html_body":{"type":"string","maxLength":1000000,"description":"HTML body, preserved when saved."},"custom_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom X-* headers preserved with this revision. Older drafts containing reserved headers remain readable."},"attachments":{"type":"array","items":{"type":"object","properties":{"blob_id":{"type":"string","minLength":1,"maxLength":255,"description":"An attachment uploaded to this mailbox."},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"Attachment filename."},"content_type":{"type":"string","minLength":1,"maxLength":255,"description":"Attachment media type."},"size_bytes":{"type":"integer","minimum":0,"maximum":7500000,"description":"Attachment size in bytes; verified when saved."},"disposition":{"type":"string","enum":["attachment","inline"],"description":"Whether the attachment appears within the message."},"content_id":{"type":"string","minLength":1,"maxLength":998,"description":"Content ID referenced by an inline image."}},"required":["blob_id","filename","content_type","size_bytes"],"additionalProperties":false},"maxItems":10,"description":"Attachments and inline images."},"id":{"type":"string","description":"Stable draft ID."},"revision":{"type":"integer","exclusiveMinimum":0,"description":"Current draft revision."},"status":{"type":"string","enum":["preparing","ready","scheduled","sending","queued","uncertain","failed","deleted"],"description":"Saving or sending state."},"message_id":{"type":["string","null"],"description":"Saved message ID; absent until saving finishes."},"scheduled_for":{"type":["string","null"],"format":"date-time","description":"Requested earliest send time, retained after sending. Null when no schedule is set."},"schedule_version":{"type":"integer","minimum":0,"description":"Schedule control version. Changes whenever a schedule is created, moved or cancelled."},"failure_code":{"type":["string","null"],"enum":["preparation_failed","authorisation_revoked","send_rejected"],"description":"Safe failure reason. Correct failed draft content or current permissions before retrying. Never retry an uncertain send as a new message."},"reply_to_message_id":{"type":"string","description":"Original message this draft replies to."},"in_reply_to":{"type":"array","items":{"type":"string"},"description":"Snapshotted parent message identifiers."},"references":{"type":"array","items":{"type":"string"},"description":"Snapshotted conversation identifiers."}},"required":["id","revision","status","message_id","scheduled_for","schedule_version","failure_code","in_reply_to","references"],"additionalProperties":false},"MailboxDraftListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxDraft"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxDraftResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxDraft"}},"required":["data"]}],"unevaluatedProperties":false},"CreateMailboxDraft":{"type":"object","properties":{"from":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false,"description":"Authorised sender; defaults to this inbox."},"to":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Primary recipients; at most 50 total across To, Cc and Bcc."},"cc":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Visible copied recipients."},"bcc":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Hidden copied recipients."},"reply_to":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":20,"description":"Authorised reply addresses; defaults to this inbox."},"subject":{"type":"string","maxLength":998,"description":"Subject; may be empty."},"text_body":{"type":"string","maxLength":1000000,"description":"Plain-text body."},"html_body":{"type":"string","maxLength":1000000,"description":"HTML body, preserved when saved."},"custom_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom X-* headers. Writes reject X-SES-TENANT, X-SES-CONFIGURATION-SET and X-SES-MESSAGE-TAGS case-insensitively. On updates, omit this field to preserve saved headers, or pass {} to clear them."},"attachments":{"type":"array","items":{"type":"object","properties":{"blob_id":{"type":"string","minLength":1,"maxLength":255,"description":"An attachment uploaded to this mailbox."},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"Attachment filename."},"content_type":{"type":"string","minLength":1,"maxLength":255,"description":"Attachment media type."},"size_bytes":{"type":"integer","minimum":0,"maximum":7500000,"description":"Attachment size in bytes; verified when saved."},"disposition":{"type":"string","enum":["attachment","inline"],"description":"Whether the attachment appears within the message."},"content_id":{"type":"string","minLength":1,"maxLength":998,"description":"Content ID referenced by an inline image."}},"required":["blob_id","filename","content_type","size_bytes"],"additionalProperties":false},"maxItems":10,"description":"Attachments and inline images."},"source":{"type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":255,"description":"Source message in this inbox."},"action":{"type":"string","enum":["reply","reply_all","forward","adopt"],"description":"Prepare a reply, reply-all, forward or adopt an existing draft. Source content and attachments are saved with the draft."}},"required":["message_id","action"],"additionalProperties":false,"description":"Source for this draft. Adoption requires Idempotency-Key. Explicit content fields override prepared defaults."},"reply_to_message_id":{"type":"string","minLength":1,"maxLength":255,"description":"Message in this inbox to reply to; thread headers are snapshotted."}},"additionalProperties":false},"SendMailboxDraft":{"type":"object","properties":{"expected_revision":{"type":"integer","exclusiveMinimum":0,"description":"Exact saved revision to send. A stale revision returns conflict."},"expected_schedule_version":{"type":"integer","minimum":0,"maximum":2147483647,"description":"Current schedule version. Required for scheduling and after cancelling a schedule."},"scheduled_for":{"type":"string","format":"date-time","description":"Send no earlier than this future time, within 30 days. Include a timezone and at most millisecond precision. Omit to send now."}},"required":["expected_revision"],"additionalProperties":false},"MailboxDraftDeleteResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"ControlMailboxDraftSchedule":{"type":"object","properties":{"expected_revision":{"type":"integer","exclusiveMinimum":0,"description":"Exact saved content revision."},"expected_schedule_version":{"type":"integer","minimum":0,"maximum":2147483647,"description":"Current schedule version; stale requests return conflict. Repeating the last identical request returns its current result."},"scheduled_for":{"type":["string","null"],"format":"date-time","description":"New future time within 30 days, or null to cancel and make the draft editable. Cancellation fails once sending has begun."}},"required":["expected_revision","expected_schedule_version","scheduled_for"],"additionalProperties":false},"UpdateMailboxDraft":{"type":"object","properties":{"from":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false,"description":"Authorised sender; defaults to this inbox."},"to":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Primary recipients; at most 50 total across To, Cc and Bcc."},"cc":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Visible copied recipients."},"bcc":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":50,"description":"Hidden copied recipients."},"reply_to":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email address."},"name":{"type":["string","null"],"maxLength":255,"description":"Display name."}},"required":["email"],"additionalProperties":false},"maxItems":20,"description":"Authorised reply addresses; defaults to this inbox."},"subject":{"type":"string","maxLength":998,"description":"Subject; may be empty."},"text_body":{"type":"string","maxLength":1000000,"description":"Plain-text body."},"html_body":{"type":"string","maxLength":1000000,"description":"HTML body, preserved when saved."},"custom_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom X-* headers. Writes reject X-SES-TENANT, X-SES-CONFIGURATION-SET and X-SES-MESSAGE-TAGS case-insensitively. On updates, omit this field to preserve saved headers, or pass {} to clear them."},"attachments":{"type":"array","items":{"type":"object","properties":{"blob_id":{"type":"string","minLength":1,"maxLength":255,"description":"An attachment uploaded to this mailbox."},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"Attachment filename."},"content_type":{"type":"string","minLength":1,"maxLength":255,"description":"Attachment media type."},"size_bytes":{"type":"integer","minimum":0,"maximum":7500000,"description":"Attachment size in bytes; verified when saved."},"disposition":{"type":"string","enum":["attachment","inline"],"description":"Whether the attachment appears within the message."},"content_id":{"type":"string","minLength":1,"maxLength":998,"description":"Content ID referenced by an inline image."}},"required":["blob_id","filename","content_type","size_bytes"],"additionalProperties":false},"maxItems":10,"description":"Attachments and inline images."},"expected_revision":{"type":"integer","exclusiveMinimum":0,"description":"The revision that was reviewed; a stale value returns conflict."}},"required":["expected_revision"],"additionalProperties":false},"MailboxAttachmentText":{"type":"object","properties":{"id":{"type":"string","description":"Extraction ID.","example":"ext_example"},"status":{"type":"string","enum":["pending","running","complete"],"description":"Poll until complete to read the outcome."},"outcome":{"anyOf":[{"type":"string","enum":["ready","unsupported","encrypted","malformed","ocr_required","resource_limit","source_unavailable","failed"]},{"type":"null"}],"description":"Null while pending or running. Only ready contains extracted text; other outcomes contain an empty string."},"text":{"type":["string","null"],"description":"Markdown text, or null until complete. Limited to max_bytes in UTF-8."},"format":{"type":"string","enum":["markdown"],"description":"Extracted text format."},"truncated":{"type":"boolean","description":"True when conversion or the requested output bound omitted text."},"expires_at":{"type":"string","format":"date-time","description":"Cache expiry. A new POST is needed after expiry."}},"required":["id","status","outcome","text","format","truncated","expires_at"],"additionalProperties":false},"MailboxAttachmentTextResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxAttachmentText"}},"required":["data"]}],"unevaluatedProperties":false},"MailboxSenderChoices":{"type":"object","properties":{"origin_address":{"type":"string","format":"email","description":"Originating inbox address; authorisation and billing remain attached to this inbox."},"from":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":1702},"domains":{"type":"array","items":{"type":"string","maxLength":253},"maxItems":100}},"required":["addresses","domains"],"additionalProperties":false,"description":"Permitted exact From addresses and verified domains. Domains allow any localpart on that exact domain."},"reply_to":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":1702},"domains":{"type":"array","items":{"type":"string","maxLength":253},"maxItems":100}},"required":["addresses","domains"],"additionalProperties":false,"description":"Permitted exact Reply-To addresses and domains. The originating inbox is the default when permitted."}},"required":["origin_address","from","reply_to"],"additionalProperties":false},"MailboxSenderChoicesResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MailboxSenderChoices"}},"required":["data"]}],"unevaluatedProperties":false},"FilterRule":{"type":"object","properties":{"type":{"type":"string","enum":["allow","deny"],"description":"Rule type"},"pattern":{"type":"string","description":"Email address or bare domain name. Validated against RFC 5321/1035 regexes. The `*@domain` wildcard spelling is accepted and normalised to the bare domain (matching is by exact address or sender domain).","example":"partner.com"},"note":{"type":["string","null"],"maxLength":255,"description":"Free-form caption for the rule (≤255 chars). UI-only metadata — never consulted at match time. `null` when absent.","example":"billing webhooks"}},"required":["type","pattern"],"additionalProperties":false},"FilterState":{"type":"object","properties":{"mode":{"type":"string","enum":["off","allowlist","denylist"],"description":"Active filtering mode. `off` disables filtering (all senders accepted). `allowlist` only accepts senders matching a rule. `denylist` blocks senders matching a rule."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/FilterRule"},"description":"Current rules, sorted by pattern ascending"}},"required":["mode","rules"],"additionalProperties":false},"FilterStateResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/FilterState"}},"required":["data"]}],"unevaluatedProperties":false},"SetFilterStateBody":{"type":"object","properties":{"mode":{"type":"string","enum":["off","allowlist","denylist"]},"rules":{"type":"array","items":{"$ref":"#/components/schemas/FilterRule"},"maxItems":1000,"description":"Replacement rule set. Maximum 1000 rules per request. An empty array is valid (no rules)."}},"required":["mode","rules"],"additionalProperties":false},"IncomingLogItem":{"type":"object","properties":{"id":{"type":"string","description":"Incoming log public ID","example":"ilog_9ed2f2fdbacf38ef05c6a8b9"},"mailbox_id":{"type":["string","null"],"description":"Mailbox public ID"},"mailbox_email":{"type":["string","null"],"description":"Mailbox email address"},"event_type":{"type":"string","enum":["message.received","message.received.spam"]},"message_id":{"type":["string","null"],"description":"Message identifier when available"},"message_id_kind":{"type":["string","null"],"description":"Identifier source when available"},"from_email":{"type":["string","null"]},"to_emails":{"type":"array","items":{"type":"string"}},"subject":{"type":["string","null"]},"size_bytes":{"type":["number","null"]},"received_at":{"type":"string","description":"ISO 8601 received timestamp"},"is_spam":{"type":"boolean"},"billing_bucket_start":{"type":"string","description":"ISO 8601 usage bucket start"},"unit_amount":{"type":"string","description":"Per-message unit amount in USD"},"amount":{"type":"string","description":"Billable amount for this message in USD"}},"required":["id","mailbox_id","mailbox_email","event_type","message_id","message_id_kind","from_email","to_emails","subject","size_bytes","received_at","is_spam","billing_bucket_start","unit_amount","amount"],"additionalProperties":false},"IncomingLogItemCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/IncomingLogItem"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"IncomingLogItemResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/IncomingLogItem"}},"required":["data"]}],"unevaluatedProperties":false},"WebhookFilters":{"type":"object","properties":{"mailbox_ids":{"type":"array","items":{"type":"string"},"description":"Mailbox public IDs to receive events for. Empty means all mailboxes in the team.","example":["mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"]}},"required":["mailbox_ids"],"additionalProperties":false,"description":"Optional delivery scope. Empty mailbox_ids means all team mailboxes."},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string","description":"Webhook public ID","example":"whk_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"name":{"type":["string","null"],"description":"Optional human-friendly label used in dashboard list/detail pages. May be `null` for subscriptions created without a name.","example":"Acme inbound forwarder"},"url":{"type":"string","format":"uri","description":"HTTPS endpoint that receives signed event POSTs.","example":"https://hooks.acme.com/sendmux"},"event_types":{"type":"array","items":{"type":"string","enum":["message.delivered","message.bounced","message.complained","message.rejected","message.delivery_delayed","message.received","message.received.spam","calendar.changed","sendmux.test"],"description":"Event types a webhook may subscribe to. `sendmux.test` is accepted so you can verify end-to-end delivery via POST /webhooks/{id}/test.","example":"message.bounced"},"description":"Event types this subscription receives.","example":["message.bounced","message.received"]},"filters":{"$ref":"#/components/schemas/WebhookFilters"},"enabled":{"type":"boolean","description":"When false, no events are delivered to this subscription.","example":true},"failing":{"type":"boolean","description":"True when the 24-hour retry window has been exhausted for this subscription. Reset by updating the subscription (e.g. fixing the URL) and re-enabling.","example":false},"created_at":{"type":"string","description":"ISO 8601 creation timestamp","example":"2026-04-23T09:12:00Z"},"updated_at":{"type":"string","description":"ISO 8601 last-modified timestamp","example":"2026-04-23T09:12:00Z"}},"required":["id","name","url","event_types","filters","enabled","failing","created_at","updated_at"],"additionalProperties":false},"WebhookSubscriptionCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"WebhookSubscriptionWithSecret":{"type":"object","properties":{"id":{"type":"string","description":"Webhook public ID","example":"whk_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"name":{"type":["string","null"],"description":"Optional human-friendly label used in dashboard list/detail pages. May be `null` for subscriptions created without a name.","example":"Acme inbound forwarder"},"url":{"type":"string","format":"uri","description":"HTTPS endpoint that receives signed event POSTs.","example":"https://hooks.acme.com/sendmux"},"event_types":{"type":"array","items":{"type":"string","enum":["message.delivered","message.bounced","message.complained","message.rejected","message.delivery_delayed","message.received","message.received.spam","calendar.changed","sendmux.test"],"description":"Event types a webhook may subscribe to. `sendmux.test` is accepted so you can verify end-to-end delivery via POST /webhooks/{id}/test.","example":"message.bounced"},"description":"Event types this subscription receives.","example":["message.bounced","message.received"]},"filters":{"$ref":"#/components/schemas/WebhookFilters"},"enabled":{"type":"boolean","description":"When false, no events are delivered to this subscription.","example":true},"failing":{"type":"boolean","description":"True when the 24-hour retry window has been exhausted for this subscription. Reset by updating the subscription (e.g. fixing the URL) and re-enabling.","example":false},"created_at":{"type":"string","description":"ISO 8601 creation timestamp","example":"2026-04-23T09:12:00Z"},"updated_at":{"type":"string","description":"ISO 8601 last-modified timestamp","example":"2026-04-23T09:12:00Z"},"secret":{"type":"string","description":"Signing secret for both webhook signature versions. X-Qubrics-Signature signs the exact body bytes. X-Qubrics-Signature-V2 contains v1=<hex HMAC-SHA256> and signs X-Qubrics-Timestamp (Unix seconds), a full stop, then the exact body bytes. The X-Sendmux-Signature, X-Sendmux-Signature-V2 and X-Sendmux-Timestamp headers carry the same values and remain supported indefinitely. Check timestamp freshness and compare signatures in constant time before parsing the body. Store this secret securely. It is returned only on creation and rotation. Use POST /webhooks/{id}/rotate-secret to issue a new one.","example":"whsec_a9f3c2…"}},"required":["id","name","url","event_types","filters","enabled","failing","created_at","updated_at","secret"],"additionalProperties":false},"WebhookSubscriptionWithSecretResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/WebhookSubscriptionWithSecret"}},"required":["data"]}],"unevaluatedProperties":false},"WebhookCreateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-friendly label (max 255 chars). Surfaced in dashboard list/detail views.","example":"Acme inbound forwarder"},"url":{"type":"string","format":"uri","description":"HTTPS endpoint that will receive event POSTs. Must be https:// — plain HTTP is rejected.","example":"https://hooks.acme.com/sendmux"},"event_types":{"type":"array","items":{"type":"string","enum":["message.delivered","message.bounced","message.complained","message.rejected","message.delivery_delayed","message.received","message.received.spam","calendar.changed","sendmux.test"],"description":"Event types a webhook may subscribe to. `sendmux.test` is accepted so you can verify end-to-end delivery via POST /webhooks/{id}/test.","example":"message.bounced"},"minItems":1,"description":"At least one event type must be provided.","example":["message.bounced","message.received"]},"filters":{"allOf":[{"$ref":"#/components/schemas/WebhookFilters"},{"description":"Optional delivery scope. Omit or pass an empty mailbox_ids array to receive matching events for all mailboxes in the team."}]},"enabled":{"type":"boolean","description":"Defaults to true.","example":true}},"required":["url","event_types"],"additionalProperties":false},"WebhookSubscriptionResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/WebhookSubscription"}},"required":["data"]}],"unevaluatedProperties":false},"WebhookUpdateBody":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":255,"description":"Replace the human-friendly label. Send `null` to clear it; omit to leave unchanged."},"url":{"type":"string","format":"uri","description":"New HTTPS endpoint. Must be https://."},"event_types":{"type":"array","items":{"type":"string","enum":["message.delivered","message.bounced","message.complained","message.rejected","message.delivery_delayed","message.received","message.received.spam","calendar.changed","sendmux.test"],"description":"Event types a webhook may subscribe to. `sendmux.test` is accepted so you can verify end-to-end delivery via POST /webhooks/{id}/test.","example":"message.bounced"},"minItems":1,"description":"Replaces the full event-type list. At least one must be provided."},"filters":{"allOf":[{"$ref":"#/components/schemas/WebhookFilters"},{"description":"Replaces the full delivery scope. Omit to leave unchanged; pass an empty mailbox_ids array for all team mailboxes."}]},"enabled":{"type":"boolean","description":"When toggled from false to true, also clears the `failing` flag — retry deliveries resume on the next matching event."}},"additionalProperties":false},"WebhookDeletedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}},"required":["data"]}],"unevaluatedProperties":false},"WebhookDeliveryAttempt":{"type":"object","properties":{"id":{"type":"string","description":"Delivery-attempt public ID","example":"whda_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"event_id":{"type":"string","description":"Webhook event ID","example":"evt_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"event_type":{"type":"string","enum":["message.delivered","message.bounced","message.complained","message.rejected","message.delivery_delayed","message.received","message.received.spam","calendar.changed","sendmux.test"],"description":"Event types a webhook may subscribe to. `sendmux.test` is accepted so you can verify end-to-end delivery via POST /webhooks/{id}/test.","example":"message.bounced"},"result":{"type":"string","enum":["success","retrying","failed","permanent_failure"],"description":"Delivery result for this attempt.","example":"success"},"response_status":{"type":["integer","null"],"description":"HTTP status returned by the endpoint, or null for network/timeout failures.","example":200},"response_ms":{"type":"integer","minimum":0,"description":"End-to-end delivery latency in milliseconds.","example":184},"delivery_attempt":{"type":"integer","exclusiveMinimum":0,"description":"1-based retry attempt number.","example":1},"max_attempts":{"type":"integer","exclusiveMinimum":0,"description":"Maximum attempts before the subscription is marked failing.","example":8},"next_retry_at":{"type":["string","null"],"description":"Next retry timestamp when result is retrying; otherwise null.","example":null},"error_message":{"type":["string","null"],"description":"Public-safe network error category when no HTTP response was received.","example":null},"response_body":{"type":["string","null"],"description":"Truncated endpoint response preview, if any.","example":"ok"},"payload_available":{"type":"boolean","description":"True while the delivered request payload can still be fetched.","example":true},"payload_expires_at":{"type":"string","description":"Timestamp when the retained request payload expires.","example":"2026-05-28T09:12:00Z"},"request_payload_bytes":{"type":"integer","minimum":0,"description":"Size of the delivered request payload in bytes.","example":2048},"request_payload_sha256":{"type":["string","null"],"description":"SHA-256 digest of the delivered request payload.","example":"b1946ac92492d2347c6235b4d2611184d4e4f8f2f43a5f2d8d5b7a4a6f0c1e2d"},"created_at":{"type":"string","description":"ISO 8601 attempt timestamp","example":"2026-05-21T09:12:00Z"}},"required":["id","event_id","event_type","result","response_status","response_ms","delivery_attempt","max_attempts","next_retry_at","error_message","response_body","payload_available","payload_expires_at","request_payload_bytes","request_payload_sha256","created_at"],"additionalProperties":false},"WebhookDeliveryAttemptCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliveryAttempt"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"WebhookEventData":{"type":"object","properties":{"message_id":{"type":["string","null"],"description":"Message identifier from the event source.","example":"ME3P282MB076951B3AAD3255D686EA8EDCA0F2@example.com"},"message_id_kind":{"type":["string","null"],"enum":["provider","rfc5322"],"description":"`provider` for sending feedback IDs; `rfc5322` for inbound email Message-ID header values.","example":"rfc5322"},"sendmux_message_id":{"type":["string","null"],"description":"Compatibility alias of qubrics_message_id for outbound sending feedback.","example":null},"qubrics_message_id":{"type":["string","null"],"description":"Qubrics message correlation ID, equal to sendmux_message_id. May be absent from older retained events.","example":null},"sender":{"type":["string","null"],"description":"Sender/envelope-from address when available.","example":"sender@example.com"},"recipients":{"type":"array","items":{"type":"string"},"description":"All affected recipients. Empty for synthetic test events.","example":["inbox@example.com"]},"mailbox_id":{"type":["string","null"],"description":"Mailbox public ID for inbound mailbox events when resolved.","example":"mbx_123"},"bounce_type":{"type":["string","null"],"enum":["Permanent","Transient","Undetermined"],"description":"Bounce category for `message.bounced` events.","example":null},"bounce_subtype":{"type":["string","null"],"description":"More specific bounce category when available.","example":null},"complaint_type":{"type":["string","null"],"description":"Complaint category for `message.complained` events.","example":null},"complaint_subtype":{"type":["string","null"],"description":"More specific complaint category when available.","example":null},"reject_reason":{"type":["string","null"],"description":"Reject reason for `message.rejected` events.","example":null},"delay_type":{"type":["string","null"],"description":"Delay category for `message.delivery_delayed` events.","example":null},"delay_expires_at":{"type":["string","null"],"description":"When delivery retries are expected to stop, when provided.","example":null},"is_spam":{"type":["boolean","null"],"description":"Only populated for inbound mailbox events.","example":false},"webhook_id":{"type":["string","null"],"description":"Target webhook ID for synthetic `sendmux.test` payloads.","example":null}},"required":["message_id","message_id_kind","sendmux_message_id","sender","recipients","mailbox_id","bounce_type","bounce_subtype","complaint_type","complaint_subtype","reject_reason","delay_type","delay_expires_at","is_spam","webhook_id"],"additionalProperties":false},"MailWebhookEventPayload":{"type":"object","properties":{"id":{"type":"string","description":"Stable per-event identifier. Also sent in the X-Qubrics-Event-Id and X-Sendmux-Event-Id headers.","example":"evt_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"type":{"type":"string","enum":["message.delivered","message.bounced","message.complained","message.rejected","message.delivery_delayed","message.received","message.received.spam","sendmux.test"],"description":"Dotted event type. Same value as the X-Qubrics-Event-Type and X-Sendmux-Event-Type headers.","example":"message.received"},"team_public_id":{"type":"string","description":"Team that owns the event.","example":"team_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"occurred_at":{"type":"string","description":"When the event occurred.","example":"2026-05-21T09:12:00Z"},"data":{"$ref":"#/components/schemas/WebhookEventData"}},"required":["id","type","team_public_id","occurred_at","data"],"additionalProperties":false},"CalendarWebhookEventData":{"type":"object","properties":{"mailbox_id":{"type":"string"},"resource":{"type":"string","enum":["calendar","event"]},"created":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"maxItems":100},"updated":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"maxItems":100},"destroyed":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"maxItems":100},"old_state":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"new_state":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque identifier scoped to the selected mailbox."},"has_more":{"type":"boolean"},"sync_required":{"type":"boolean"}},"required":["mailbox_id","resource","created","updated","destroyed","old_state","new_state","has_more","sync_required"],"additionalProperties":false},"CalendarWebhookEventPayload":{"type":"object","properties":{"id":{"type":"string","description":"Stable per-event identifier. Also sent in the X-Qubrics-Event-Id and X-Sendmux-Event-Id headers.","example":"evt_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"type":{"type":"string","enum":["calendar.changed"]},"team_public_id":{"type":"string","description":"Team that owns the event.","example":"team_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"occurred_at":{"type":"string","description":"When the event occurred.","example":"2026-05-21T09:12:00Z"},"data":{"$ref":"#/components/schemas/CalendarWebhookEventData"}},"required":["id","type","team_public_id","occurred_at","data"],"additionalProperties":false},"WebhookEventPayload":{"oneOf":[{"$ref":"#/components/schemas/MailWebhookEventPayload"},{"$ref":"#/components/schemas/CalendarWebhookEventPayload"}],"discriminator":{"propertyName":"type","mapping":{"message.delivered":"#/components/schemas/MailWebhookEventPayload","message.bounced":"#/components/schemas/MailWebhookEventPayload","message.complained":"#/components/schemas/MailWebhookEventPayload","message.rejected":"#/components/schemas/MailWebhookEventPayload","message.delivery_delayed":"#/components/schemas/MailWebhookEventPayload","message.received":"#/components/schemas/MailWebhookEventPayload","message.received.spam":"#/components/schemas/MailWebhookEventPayload","sendmux.test":"#/components/schemas/MailWebhookEventPayload","calendar.changed":"#/components/schemas/CalendarWebhookEventPayload"}},"description":"The JSON request body delivered to the webhook endpoint.","example":{"id":"evt_clxxxxxxxxxxxxxxxxxxxxxxxxx","type":"message.received","team_public_id":"team_clxxxxxxxxxxxxxxxxxxxxxxxxx","occurred_at":"2026-05-21T09:12:00Z","data":{"message_id":"ME3P282MB076951B3AAD3255D686EA8EDCA0F2@example.com","message_id_kind":"rfc5322","sendmux_message_id":null,"qubrics_message_id":null,"sender":"sender@example.com","recipients":["inbox@example.com"],"mailbox_id":"mbx_123","bounce_type":null,"bounce_subtype":null,"complaint_type":null,"complaint_subtype":null,"reject_reason":null,"delay_type":null,"delay_expires_at":null,"is_spam":false,"webhook_id":null}}},"WebhookDeliveryPayload":{"type":"object","properties":{"id":{"type":"string","description":"Delivery-attempt public ID","example":"whda_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"event_id":{"type":"string","description":"Webhook event ID","example":"evt_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"event_type":{"type":"string","enum":["message.delivered","message.bounced","message.complained","message.rejected","message.delivery_delayed","message.received","message.received.spam","calendar.changed","sendmux.test"],"description":"Event types a webhook may subscribe to. `sendmux.test` is accepted so you can verify end-to-end delivery via POST /webhooks/{id}/test.","example":"message.bounced"},"delivery_attempt":{"type":"integer","exclusiveMinimum":0,"description":"1-based retry attempt number.","example":1},"created_at":{"type":"string","description":"ISO 8601 attempt timestamp","example":"2026-05-21T09:12:00Z"},"expires_at":{"type":"string","description":"Timestamp when this retained payload expires.","example":"2026-05-28T09:12:00Z"},"payload":{"$ref":"#/components/schemas/WebhookEventPayload"}},"required":["id","event_id","event_type","delivery_attempt","created_at","expires_at","payload"],"additionalProperties":false},"WebhookDeliveryPayloadResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/WebhookDeliveryPayload"}},"required":["data"]}],"unevaluatedProperties":false},"WebhookTestResponse":{"type":"object","properties":{"event_id":{"type":"string","description":"The event_id attached to the X-Qubrics-Event-Id and X-Sendmux-Event-Id headers of the test delivery.","example":"evt_clxxxxxxxxxxxxxxxxxxxxxxxxx"}},"required":["event_id"],"additionalProperties":false}},"parameters":{}},"paths":{"/mailbox-send-policies/{scope}/{public_id}":{"get":{"operationId":"managementGetMailboxSendPolicy","summary":"Get a sending policy","description":"Sender, Reply-To and recipient restrictions intersect across team, inbox and credential policies. Requires an administrative connection: team.read/team.update for team policies, mailbox.admin.read/mailbox.admin.manage for inbox policies, or key.read/key.* for credential policies. Integration and mailbox keys cannot manage these policies.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["team.read"]},{"oauth2":["mailbox.admin.read"]},{"oauth2":["key.read"]}],"parameters":[{"schema":{"type":"string","enum":["team","mailbox","api_key","oauth_grant","agent_registration"],"description":"Policy level to read or replace."},"required":true,"description":"Policy level to read or replace.","name":"scope","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Public ID of the team, inbox, API key, connected-app grant or agent registration."},"required":true,"description":"Public ID of the team, inbox, API key, connected-app grant or agent registration.","name":"public_id","in":"path"},{"schema":{"type":"string","description":"Return 304 when this ETag still matches."},"required":false,"description":"Return 304 when this ETag still matches.","name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Current sending policy.","headers":{"ETag":{"description":"Exact version to use for conditional reads and replacement.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxSendPolicyResponse"}}}},"304":{"description":"The policy is unchanged.","headers":{"ETag":{"description":"Current policy version.","schema":{"type":"string"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"put":{"operationId":"managementReplaceMailboxSendPolicy","summary":"Replace a sending policy","description":"Sender, Reply-To and recipient restrictions intersect across team, inbox and credential policies. Requires an administrative connection: team.read/team.update for team policies, mailbox.admin.read/mailbox.admin.manage for inbox policies, or key.read/key.* for credential policies. Integration and mailbox keys cannot manage these policies.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["team.update"]},{"oauth2":["mailbox.admin.manage"]},{"oauth2":["key.*"]}],"parameters":[{"schema":{"type":"string","enum":["team","mailbox","api_key","oauth_grant","agent_registration"],"description":"Policy level to read or replace."},"required":true,"description":"Policy level to read or replace.","name":"scope","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Public ID of the team, inbox, API key, connected-app grant or agent registration."},"required":true,"description":"Public ID of the team, inbox, API key, connected-app grant or agent registration.","name":"public_id","in":"path"},{"schema":{"type":"string","description":"Required exact ETag from the current policy. Wildcards are not accepted."},"required":true,"description":"Required exact ETag from the current policy. Wildcards are not accepted.","name":"If-Match","in":"header"},{"schema":{"type":"string","description":"Reuse with the same policy and ETag to replay a successful replacement."},"required":false,"description":"Reuse with the same policy and ETag to replay a successful replacement.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceMailboxSendPolicy"}}}},"responses":{"200":{"description":"Current sending policy.","headers":{"ETag":{"description":"Exact version to use for conditional reads and replacement.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxSendPolicyResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/me":{"get":{"operationId":"managementGetConnection","tags":["Connection"],"summary":"Get Management connection","description":"Validate this credential and return its team, connection label, permissions and authorised mailboxes. No additional read permission or mailbox selection is required. Mailbox storage and sending availability are not checked. No user profile or secrets are returned.","security":[{"bearerAuth":[]},{"oauth2":[]}],"parameters":[{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag from a previous response. A match returns 304 with no body after rechecking authentication."}],"responses":{"200":{"description":"Connection information","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Always no-store."},"X-Request-Id":{"schema":{"type":"string"},"description":"Request identifier."},"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionResponse"}}}},"304":{"description":"Connection information is unchanged. Authentication is checked on every request.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Always no-store."},"X-Request-Id":{"schema":{"type":"string"},"description":"Request identifier."}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential is not authorised for this API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/connection":{"get":{"operationId":"mailboxGetConnection","tags":["Mailbox API"],"summary":"Get Mailbox connection","description":"Validate this credential and return its team, connection label, permissions and authorised mailboxes. No additional read permission or mailbox selection is required. Mailbox storage and sending availability are not checked. No user profile or secrets are returned.","security":[{"bearerAuth":[]},{"oauth2":[]}],"parameters":[{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag from a previous response. A match returns 304 with no body after rechecking authentication."}],"responses":{"200":{"description":"Connection information","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Always no-store."},"X-Request-Id":{"schema":{"type":"string"},"description":"Request identifier."},"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionResponse"}}}},"304":{"description":"Connection information is unchanged. Authentication is checked on every request.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Always no-store."},"X-Request-Id":{"schema":{"type":"string"},"description":"Request identifier."}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential is not authorised for this API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers/stats":{"get":{"operationId":"managementGetProviderStats","summary":"Get sending account statistics","description":"Returns aggregate counts of configured sending accounts with breakdowns by type and status.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.read"]}],"responses":{"200":{"description":"Sending account statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderStatsResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers":{"get":{"operationId":"managementListProviders","summary":"List sending accounts","description":"Returns a cursor-paginated list of sending accounts. Credentials are never returned. The shared Amazon SES account is included and marked with `is_shared: true`.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["active","inactive","error","pending"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["smtp","gmail_api","outlook_api","amazon_ses"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Sending account list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderItemCursorListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"managementCreateProvider","summary":"Create an SMTP sending account","description":"Creates a custom SMTP sending account. Supply an `Idempotency-Key` header to safely retry on network errors. The SMTP password is stored securely and is never returned.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.create"]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"providers-create-20260525-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderCreateBody"}}}},"responses":{"201":{"description":"Sending account created","headers":{"Location":{"description":"Canonical GET URL for the new sending account.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderItemResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Limit reached or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers/shared-amazon-ses-limit-request/{request_id}":{"delete":{"operationId":"managementCancelSharedAmazonSesLimitRequest","summary":"Cancel a shared Amazon SES daily limit request","description":"Cancels a pending shared Amazon SES daily limit increase request for the caller's team. Approved or denied requests cannot be cancelled.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.update"]}],"parameters":[{"schema":{"type":"string","description":"Shared Amazon SES limit request public ID","example":"slir_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"request_id","in":"path"}],"responses":{"200":{"description":"Request cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequestCancelResponse"}}}},"404":{"description":"Request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request has already been approved or denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers/{public_id}":{"get":{"operationId":"managementGetProvider","summary":"Get a sending account","description":"Returns one sending account. Responses include an ETag for conditional GET and optimistic PATCH.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.read"]}],"parameters":[{"schema":{"type":"string","description":"Sending account public ID","example":"dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Sending account","headers":{"ETag":{"description":"Weak ETag.","schema":{"type":"string","example":"W/\"a1b2c3d4e5f60718\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderItemResponse"}}}},"304":{"description":"Not Modified"},"404":{"description":"Sending account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"managementUpdateProvider","summary":"Update a sending account","description":"Updates a custom sending account or replaces variables on the shared Amazon SES account. Shared-account connection settings cannot be edited; use activate/deactivate and the limit-request endpoint for its other allowed actions.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.update"]}],"parameters":[{"schema":{"type":"string","description":"Sending account public ID","example":"dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs."},"required":false,"name":"If-Match","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderUpdateBody"}}}},"responses":{"200":{"description":"Updated sending account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderItemResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Sending account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"ETag conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Shared-account lock or unsupported field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"managementDeleteProvider","summary":"Delete a sending account","description":"Deletes a custom or connected sending account. The shared Amazon SES account cannot be deleted.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.delete"]}],"parameters":[{"schema":{"type":"string","description":"Sending account public ID","example":"dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderDeletedResponse"}}}},"404":{"description":"Sending account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Shared account cannot be deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers/{public_id}/activate":{"post":{"operationId":"managementActivateProvider","summary":"Activate a sending account","description":"Enables a sending account. OAuth accounts without an active connection are moved to pending until reconnected in the dashboard. The shared Amazon SES account can be activated.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.update"]}],"parameters":[{"schema":{"type":"string","description":"Sending account public ID","example":"dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"providers-create-20260525-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Updated sending account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderItemResponse"}}}},"404":{"description":"Sending account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers/{public_id}/deactivate":{"post":{"operationId":"managementDeactivateProvider","summary":"Deactivate a sending account","description":"Disables a sending account. The shared Amazon SES account can be deactivated.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.update"]}],"parameters":[{"schema":{"type":"string","description":"Sending account public ID","example":"dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"providers-create-20260525-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Updated sending account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderItemResponse"}}}},"404":{"description":"Sending account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers/{public_id}/test":{"post":{"operationId":"managementTestProvider","summary":"Test an SMTP sending account","description":"Runs a connection test for a custom SMTP account. The shared Amazon SES account and OAuth accounts cannot be tested through this endpoint.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.update"]}],"parameters":[{"schema":{"type":"string","description":"Sending account public ID","example":"dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"providers-create-20260525-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Connection test result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderTestResultResponse"}}}},"404":{"description":"Sending account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Account cannot be tested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Connection testing unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers/usage":{"get":{"operationId":"managementGetProviderUsage","summary":"Get sending account usage","description":"Returns per-account delivery-log counts for today and the trailing 7-day window.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.read"]}],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderUsageResponse"}}}}}}},"/providers/limits":{"get":{"operationId":"managementGetProviderLimits","summary":"Get sending account limits","description":"Returns custom-account capacity and shared Amazon SES daily sending limit state.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.read"]}],"responses":{"200":{"description":"Limit state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderLimitsResponse"}}}}}}},"/providers/limits/sending-accounts/request-increase":{"post":{"operationId":"managementRequestSendingAccountLimitIncrease","summary":"Request a sending account limit increase","description":"Creates a request to increase the number of custom or connected sending accounts allowed for the team.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.create"]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"providers-create-20260525-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Request submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendingAccountLimitRequestResponse"}}}},"403":{"description":"Free plan limits are fixed; upgrade to Pro to add more sending accounts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"A request is already pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Increase request is not available yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/providers/shared-amazon-ses-limit-request":{"get":{"operationId":"managementGetSharedAmazonSesLimitRequest","summary":"Get shared Amazon SES limit request state","description":"Returns the shared Amazon SES daily limit state and any pending increase request.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.read"]}],"responses":{"200":{"description":"Shared Amazon SES limit request state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequestPageResponse"}}}}}},"post":{"operationId":"managementCreateSharedAmazonSesLimitRequest","summary":"Request a shared Amazon SES daily limit increase","description":"Creates a review request for the shared Amazon SES daily sending limit. This does not modify the limit directly.","tags":["Sending accounts"],"security":[{"bearerAuth":[]},{"oauth2":["provider.update"]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"providers-create-20260525-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Request submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequestCreateResponse"}}}},"403":{"description":"Free plan limits are fixed; upgrade to Pro to increase the managed sending limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Shared Amazon SES account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"A request is already pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Increase request is not available yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/emails/metrics":{"get":{"operationId":"managementGetEmailMetrics","summary":"Get email metrics","description":"Returns aggregated email delivery counts with flexible time windowing and comparison period.","tags":["Emails"],"security":[{"bearerAuth":[]},{"oauth2":["analytics.read"]}],"parameters":[{"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Preset time window (default: 24h)"},"required":false,"name":"window","in":"query"},{"schema":{"type":"string","description":"ISO 8601 start date (overrides window)"},"required":false,"name":"from_date","in":"query"},{"schema":{"type":"string","description":"ISO 8601 end date"},"required":false,"name":"to_date","in":"query"},{"schema":{"type":"string","enum":["hourly","daily"],"description":"Timeseries granularity (default: daily)"},"required":false,"name":"granularity","in":"query"},{"schema":{"type":"string","description":"Filter by provider publicId"},"required":false,"name":"provider_id","in":"query"}],"responses":{"200":{"description":"Email metrics with comparison","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMetricsResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/emails/logs":{"get":{"operationId":"managementListEmailLogs","summary":"List delivery logs","description":"Returns paginated delivery logs with cursor-based pagination and filters.","tags":["Emails"],"security":[{"bearerAuth":[]},{"oauth2":["logs.read"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max results (default 25)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor from previous page"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["pending","sent","failed","rejected"],"description":"Filter by delivery status."},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"ISO 8601 start date. Date-only values start at 00:00 UTC."},"required":false,"name":"from_date","in":"query"},{"schema":{"type":"string","description":"ISO 8601 end date. Date-only values include the full UTC day."},"required":false,"name":"to_date","in":"query"},{"schema":{"type":"string","description":"Filter by provider publicId"},"required":false,"name":"provider_id","in":"query"},{"schema":{"type":"string","description":"Search to_email, from_email, sent_from_email, subject, message_id"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"Delivery log list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryLogItemCursorListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/emails/logs/{public_id}":{"get":{"operationId":"managementGetEmailLog","summary":"Get delivery log","description":"Returns a single delivery log by its public ID. Responses carry a weak `ETag` header — send it back as `If-None-Match` on the next request and the server will return `304 Not Modified` (no body) when the log has not changed. Logs in a terminal status (sent/failed/rejected) stop changing, so 304 replay is a real bandwidth win on repeated polls.","tags":["Emails"],"security":[{"bearerAuth":[]},{"oauth2":["logs.read"]}],"parameters":[{"schema":{"type":"string","description":"Delivery log public ID (dlog_...)"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Delivery log detail","headers":{"ETag":{"description":"Weak ETag for conditional GETs.","schema":{"type":"string","example":"W/\"a1b2c3d4e5f60718\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryLogItemResponse"}}}},"304":{"description":"Not Modified — the client's cached copy (matching `If-None-Match`) is still current.","headers":{"ETag":{"description":"Current weak ETag (same as request's `If-None-Match`).","schema":{"type":"string"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/billing/balance":{"get":{"operationId":"managementListBalance","summary":"Get current balance","description":"Returns the current spendable balance.","tags":["Billing"],"security":[{"bearerAuth":[]},{"oauth2":["billing.read"]}],"responses":{"200":{"description":"Current spendable balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/billing/summary":{"get":{"operationId":"managementGetSpendSummary","summary":"Get spend summary","description":"Returns a spend summary over a configurable lookback period.","tags":["Billing"],"security":[{"bearerAuth":[]},{"oauth2":["billing.read"]}],"parameters":[{"schema":{"type":"string","enum":["7","30","90"],"description":"Lookback period in days (default: 30)"},"required":false,"name":"days","in":"query"}],"responses":{"200":{"description":"Spend summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendSummaryResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/billing/transactions":{"get":{"operationId":"managementListTransactions","summary":"List transactions","description":"Returns paginated credit transaction history with optional type filter. Uses cursor-based pagination ordered by created_at descending — pass `cursor=<next_cursor>` from the previous response to fetch the next page.","tags":["Billing"],"security":[{"bearerAuth":[]},{"oauth2":["billing.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max results (default 25, max 100)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["PURCHASE","USAGE","AUTO_TOPUP","REFUND","ADJUSTMENT"]},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"Transaction list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionCursorListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/domains":{"get":{"operationId":"managementListDomains","summary":"List mailbox domains","description":"Returns a cursor-paginated list of sending domains configured for the team, ordered by `created_at` descending. Each entry includes the DNS records the customer must place, the current verification status, and the SES DKIM state. Pass `cursor=<next_cursor>` from the previous response to fetch the next page.","tags":["Domains"],"security":[{"bearerAuth":[]},{"oauth2":["domain.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Domain list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainItemCursorListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"managementCreateDomain","summary":"Add a mailbox domain","description":"Creates a new domain and returns the DNS records the customer must place before verification can succeed. `send_only` configures outbound sending without changing MX records. `send_receive` also configures the domain for hosted mailboxes. Provisioning touches our email platform and Amazon SES; on any failure the partial state is automatically rolled back.\n\nSupply an `Idempotency-Key` header (any unique string, max 255 chars) to safely retry on network errors. Replays with the same key return the original response; replays with a different body return `409 idempotency_conflict`.","tags":["Domains"],"security":[{"bearerAuth":[]},{"oauth2":["domain.create"]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"domains-create-20260424-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Fully qualified domain name. Must be lowercased and domain-only (no scheme).","example":"mail.acme.com"},"mode":{"type":"string","enum":["send_only","send_receive"],"description":"Domain usage mode. Defaults to `send_receive` when omitted.","example":"send_only"}},"required":["domain"],"additionalProperties":false}}}},"responses":{"201":{"description":"Domain created. The response carries a `Location` header pointing at the canonical GET URL for the new domain.","headers":{"Location":{"description":"Canonical GET URL for the newly created domain.","schema":{"type":"string","example":"/api/v1/domains/mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainItemResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Domain already in use, or `Idempotency-Key` was replayed with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"SES tenant not yet provisioned for this team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/domains/{public_id}":{"patch":{"operationId":"managementUpdateDomain","summary":"Update a mailbox domain","description":"Upgrades a send-only domain to sending and receiving. Downgrades are rejected. After upgrade, the domain returns to `pending` until the required MX record verifies.","tags":["Domains"],"security":[{"bearerAuth":[]},{"oauth2":["domain.create"]}],"parameters":[{"schema":{"type":"string","description":"Domain public ID","example":"mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs."},"required":false,"name":"If-Match","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["send_receive"],"description":"The only supported update is upgrading to `send_receive`.","example":"send_receive"}},"required":["mode"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated domain","headers":{"ETag":{"description":"Weak ETag for the post-update resource.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainItemResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`If-Match` mismatch, or the domain cannot be upgraded in its current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Unsupported update. Only `{ mode: \"send_receive\" }` is accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"managementGetDomain","summary":"Get a mailbox domain","description":"Returns a single domain including its DNS records and latest verification state. Responses carry a weak `ETag` header — send it back as `If-None-Match` on the next request and the server will return `304 Not Modified` (no body) when the resource has not changed.","tags":["Domains"],"security":[{"bearerAuth":[]},{"oauth2":["domain.read"]}],"parameters":[{"schema":{"type":"string","description":"Domain public ID","example":"mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Domain","headers":{"ETag":{"description":"Weak ETag for conditional GETs.","schema":{"type":"string","example":"W/\"a1b2c3d4e5f60718\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainItemResponse"}}}},"304":{"description":"Not Modified — the client's cached copy (matching `If-None-Match`) is still current.","headers":{"ETag":{"description":"Current weak ETag (same as request's `If-None-Match`).","schema":{"type":"string"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"managementDeleteDomain","summary":"Delete a mailbox domain","description":"Removes a domain from our mail platform, Amazon SES, and Qubrics. Blocked if any active mailbox still uses the domain — delete those mailboxes first.","tags":["Domains"],"security":[{"bearerAuth":[]},{"oauth2":["domain.delete"]}],"parameters":[{"schema":{"type":"string","description":"Domain public ID"},"required":true,"name":"public_id","in":"path"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDeletedResponse"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Domain still has active mailboxes (error code `conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Deletion is temporarily unavailable; retry after the indicated delay.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/domains/{public_id}/zone-file":{"get":{"operationId":"managementGetDomainZoneFile","summary":"Download a domain as a zone file","description":"Returns the domain's DNS records formatted as a BIND-style zone file fragment. Suitable for direct paste into a DNS provider that accepts zone-file imports.","tags":["Domains"],"security":[{"bearerAuth":[]},{"oauth2":["domain.read"]}],"parameters":[{"schema":{"type":"string","description":"Domain public ID"},"required":true,"name":"public_id","in":"path"}],"responses":{"200":{"description":"Zone file (text/plain)","headers":{"Content-Disposition":{"description":"Attachment filename `<domain>.zone`.","schema":{"type":"string","example":"attachment; filename=\"mail.acme.com.zone\""}}},"content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/domains/{public_id}/verify":{"post":{"operationId":"managementVerifyDomain","summary":"Verify a mailbox domain","description":"Checks the domain's published DNS records and latest Amazon SES DKIM and MAIL FROM statuses. If every required check passes, the domain is marked verified. A previously failed domain remains failed until a complete check succeeds. Domains automatically re-verify every 6 hours — this endpoint is only needed to trigger a check on demand.","tags":["Domains"],"security":[{"bearerAuth":[]},{"oauth2":["domain.verify"]}],"parameters":[{"schema":{"type":"string","description":"Domain public ID"},"required":true,"name":"public_id","in":"path"}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainVerifyResponse"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The domain changed while verification was running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Verification is temporarily unavailable; retry after the indicated delay.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes":{"get":{"operationId":"managementListMailboxes","summary":"List mailboxes","description":"Returns a cursor-paginated list of mailboxes configured for the team, ordered by `created_at` descending. Pass `cursor=<next_cursor>` from the previous response to fetch the next page.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max results (default 50, max 100)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["true"],"description":"Set to `true` to include deleted mailboxes in the response. Default `false`. Deleted mailboxes are retained for audit and delivery history."},"required":false,"name":"include_deleted","in":"query"}],"responses":{"200":{"description":"Mailbox list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxItemCursorListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"managementCreateMailbox","summary":"Create a mailbox","description":"Provisions a new mailbox plus an initial bearer token and matching IMAP/SMTP mailbox password. The domain portion of the email must already be verified via POST /domains. If supplied, `quota_bytes` must be one of the current storage tiers: 1073741824 (1 GB), 5368709120 (5 GB), or 53687091200 (50 GB). Creation provisions resources on our mail platform and, for `@myagent.mx` addresses, on Amazon SES — any failure rolls the partial state back automatically.\n\nSupply an `Idempotency-Key` header (any unique string, max 255 chars) to safely retry on network errors. Replays with the same key return the original response; replays with a different body return `409 idempotency_conflict`.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.create"]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"mailboxes-create-20260424-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","minLength":5,"maxLength":254,"pattern":"^(?![^\\r\\n]*[\\r\\n])(?![^@]*\\.\\.)[a-zA-Z0-9_%+-](?:[a-zA-Z0-9._%+-]*[a-zA-Z0-9_%+-])?@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,63}$","description":"Mailbox email address to create."},"display_name":{"type":"string","minLength":1,"maxLength":254,"description":"Optional display name shown in outbound From headers."},"quota_bytes":{"type":"integer","minimum":1,"description":"Storage quota in bytes. Allowed values: 1073741824 (1 GB), 5368709120 (5 GB), 53687091200 (50 GB).","example":5368709120},"send_scope":{"type":"object","properties":{"type":{"type":"string","enum":["all","providers","group"],"description":"Outbound routing strategy. Use `providers` with provider_public_ids, or `group` with group_public_ids."},"provider_public_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Provider public IDs allowed for sending when type is `providers`."},"group_public_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Delivery group public IDs allowed for sending when type is `group`."}},"required":["type"],"additionalProperties":false,"description":"Optional outbound routing restrictions."}},"required":["email"],"additionalProperties":false}}}},"responses":{"201":{"description":"Mailbox created. The response carries a `Location` header pointing at the canonical GET URL for the new mailbox.","headers":{"Location":{"description":"Canonical GET URL for the newly created mailbox.","schema":{"type":"string","example":"/api/v1/mailboxes/mx_clxxxxxxxxxxxxxxxxxxxxxxxxx"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCreateResultResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Email already in use (error code `conflict`), or `Idempotency-Key` was replayed with a different body (`idempotency_conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Domain not yet verified or semantic validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Team is not yet provisioned for sending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes/availability":{"get":{"operationId":"managementCheckMailboxAvailability","summary":"Check mailbox address availability","description":"Checks whether an email address can be reserved for mailbox creation. `@myagent.mx` availability is global across all teams; custom-domain availability is scoped to the caller's team and requires a verified send/receive mailbox domain.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.create"]}],"parameters":[{"schema":{"type":"string","description":"Email address to check.","example":"agent@myagent.mx"},"required":true,"name":"email","in":"query"}],"responses":{"200":{"description":"Mailbox address availability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAvailabilityResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Management API access with mailbox.admin.create is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes/{public_id}":{"get":{"operationId":"managementGetMailbox","summary":"Get a mailbox","description":"Returns a single mailbox, tenant-scoped to the caller's team. Responses carry a weak `ETag` header — send it back as `If-None-Match` on the next request and the server will return `304 Not Modified` (no body) when the resource has not changed. The same ETag is the value to use in `If-Match` on PATCH for optimistic concurrency.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.read"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Mailbox","headers":{"ETag":{"description":"Weak ETag for conditional GETs and optimistic-concurrency PATCHes.","schema":{"type":"string","example":"W/\"a1b2c3d4e5f60718\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxItemResponse"}}}},"304":{"description":"Not Modified — the client's cached copy (matching `If-None-Match`) is still current.","headers":{"ETag":{"description":"Current weak ETag (same as request's `If-None-Match`).","schema":{"type":"string"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"managementUpdateMailbox","summary":"Update a mailbox","description":"Updates any combination of display_name, quota_bytes, and send_scope on a mailbox. The display_name and send_scope changes land in a single transaction; quota_bytes is applied afterwards because it also updates external state on our mail platform. Quota can only be set to 1073741824 (1 GB), 5368709120 (5 GB), or 53687091200 (50 GB), and cannot be shrunk below the mailbox's current usage.\n\nFor optimistic concurrency, send `If-Match: <etag>` using the ETag from a prior GET. A mismatched `If-Match` returns `409 conflict` (the server's ETag is echoed back so you can decide whether to re-fetch). Responses carry the new ETag so chained edits can pipeline without a re-GET.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs."},"required":false,"name":"If-Match","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMailboxBody"}}}},"responses":{"200":{"description":"Updated mailbox","headers":{"ETag":{"description":"Weak ETag for the post-update resource.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxItemResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`If-Match` ETag does not match the server's current version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation error — unsupported quota tier, quota below current usage, or cross-tenant send_scope reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"managementDeleteMailbox","summary":"Delete a mailbox","description":"Removes a mailbox from our mail platform, Amazon SES (for `@myagent.mx` addresses), and Qubrics. All associated API keys are revoked.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.delete"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDeletedResponse"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Deletion is waiting for final usage. Retry after the interval in Retry-After.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes/{public_id}/suspend":{"post":{"operationId":"managementSuspendMailbox","summary":"Suspend a mailbox","description":"Suspends a mailbox without deleting messages, credentials, or settings. Suspended mailboxes cannot receive mail, authenticate to mailbox protocols, or send from the mailbox address. The operation is idempotent and accepts `Idempotency-Key` for safe retries.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key).","example":"mailbox-suspend-20260424-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Suspended mailbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxItemResponse"}}}},"403":{"description":"Management API access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Mailbox is deleted, or `Idempotency-Key` was replayed with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Mailbox service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes/{public_id}/resume":{"post":{"operationId":"managementResumeMailbox","summary":"Resume a mailbox","description":"Restores a suspended mailbox so it can authenticate, receive mail, and send from the mailbox address again. The operation is idempotent and accepts `Idempotency-Key` for safe retries.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key).","example":"mailbox-resume-20260424-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Resumed mailbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxItemResponse"}}}},"403":{"description":"Management API access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Mailbox is deleted, or `Idempotency-Key` was replayed with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Mailbox service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes/{public_id}/keys":{"post":{"operationId":"managementCreateMailboxKey","summary":"Create a mailbox API key","description":"Mints an additional bearer token plus IMAP/SMTP mailbox password for an existing mailbox. The plaintext key and password are shown exactly once — store them immediately.\n\nSupply an `Idempotency-Key` header (any unique string, max 255 chars) to safely retry on network errors. Replays with the same key return the original response; replays with a different body return `409 idempotency_conflict`.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"mailbox-keys-create-20260424-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"app_name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-friendly label for the new API key."}},"required":["app_name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Mailbox API key created. The response carries a `Location` header pointing at the canonical URL for the new key.","headers":{"Location":{"description":"Canonical URL for the newly created API key.","schema":{"type":"string","example":"/api/v1/mailboxes/mx_clxxxxxxxxxxxxxxxxxxxxxxxxx/keys/smx_clxxxxxxxxxxxxxxxxxxxxxxxxx"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAppPasswordResultResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Credential limit reached (`limit_exceeded`) or idempotency key conflict (`idempotency_conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Mailbox is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Credential setup temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes/{public_id}/keys/{key_id}":{"delete":{"operationId":"managementDeleteMailboxKey","summary":"Revoke a mailbox API key","description":"Revokes a specific bearer token + matching mailbox password. Idempotent on already-revoked keys.","tags":["Mailboxes"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"API key public ID","example":"smx_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"key_id","in":"path"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxKeyDeletedResponse"}}}},"404":{"description":"Mailbox or key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/mailboxes":{"get":{"operationId":"mailboxListGrantedMailboxes","summary":"List granted mailboxes","description":"Lists the mailboxes available to the current mailbox credential or connected app. Use this before choosing a `mailbox_id` for mailbox actions when more than one mailbox is available.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Cursor from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Search by mailbox ID or email address."},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"Granted mailboxes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantedMailboxListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/me":{"get":{"operationId":"mailboxGetMe","summary":"Self-introspect the calling mailbox","description":"Returns the selected mailbox, including live storage usage. Requires a mailbox credential or OAuth grant with Mailbox API access. For credential validation without selecting a mailbox or checking storage, use GET /mailbox/connection.\n\nResponses carry a weak `ETag` header — send it back as `If-None-Match` on the next request and the server will return `304 Not Modified` (no body) when the mailbox state has not changed.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":[]}],"parameters":[{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"The calling mailbox","headers":{"ETag":{"description":"Weak ETag for conditional GETs.","schema":{"type":"string","example":"W/\"a1b2c3d4e5f60718\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMeItemResponse"}}}},"304":{"description":"Not Modified — the client's cached copy (matching `If-None-Match`) is still current.","headers":{"ETag":{"description":"Current weak ETag (same as request's `If-None-Match`).","schema":{"type":"string"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Root key used on a mailbox-scoped endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes/{public_id}/usage":{"get":{"operationId":"managementGetMailboxCostUsage","tags":["Mailboxes"],"summary":"Read mailbox costs","description":"Read cumulative mailbox costs for a half-open window: start is included and end is excluded. Requires mailbox.admin.read and team-wide mailbox access. Retained usage remains readable after mailbox deletion while the team and credential remain active. Quantities and USD amounts are decimal strings. posted_amount includes only posted charges; incurred and unbillable amounts are reported separately. A pending result can change. Settle a window only when its state is final. This read does not start or complete settlement.","security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.read"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID."},"required":true,"description":"Mailbox public ID.","name":"public_id","in":"path"},{"schema":{"type":"string","format":"date-time","description":"Inclusive start. At most millisecond precision."},"required":true,"description":"Inclusive start. At most millisecond precision.","name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Exclusive end. Must be at or after start and at most 366 days later. At most millisecond precision."},"required":true,"description":"Exclusive end. Must be at or after start and at most 366 days later. At most millisecond precision.","name":"end","in":"query"},{"schema":{"type":"string","description":"Return 304 when the authorised response is unchanged."},"required":false,"description":"Return 304 when the authorised response is unchanged.","name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Recorded mailbox costs and settlement state.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current response validator."},"Cache-Control":{"schema":{"type":"string"},"description":"Always no-store."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCostUsageResponse"}}}},"304":{"description":"Mailbox costs have not changed.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current response validator."},"Cache-Control":{"schema":{"type":"string"},"description":"Always no-store."}}},"401":{"description":"Invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Required team-wide access or permission is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mailbox usage is unavailable to this team.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid, repeated or unsupported window boundaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Usage cannot be read. Retry after the interval in Retry-After.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/session":{"get":{"operationId":"mailboxGetSession","summary":"Get mailbox API session","description":"Returns mailbox API capabilities, resource state tokens, limits, and disabled feature flags for the authenticated mailbox.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Mailbox API session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxSessionResponse"}}}},"304":{"description":"Not modified"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox API access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Mailbox service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/identity":{"get":{"operationId":"mailboxGetIdentity","summary":"Get mailbox sender identity","description":"Returns the default sender identity and signatures for the authenticated mailbox.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"responses":{"200":{"description":"Mailbox sender identity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxIdentityResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox API access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Mailbox service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}]},"patch":{"operationId":"mailboxUpdateIdentity","summary":"Update mailbox sender identity","description":"Updates the default sender name, plain text signature, and HTML signature for the authenticated mailbox.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.settings.update"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMailboxIdentityBody"}}}},"responses":{"200":{"description":"Updated mailbox sender identity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxIdentityResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox API access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Identity could not be updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Mailbox service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}]}},"/mailbox/identities":{"get":{"operationId":"mailboxListIdentities","summary":"List mailbox sender identities","description":"Returns sender identities available to the authenticated mailbox.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)."},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Identity list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxIdentityCursorListResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox API access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/submissions":{"get":{"operationId":"mailboxListSubmissions","summary":"List mailbox submissions","description":"Returns a cursor-paginated list of send submissions for the authenticated mailbox, including delivery lifecycle fields when available.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Comma-separated identity IDs, maximum 100."},"required":false,"name":"identity_ids","in":"query"},{"schema":{"type":"string","description":"Comma-separated message IDs, maximum 100."},"required":false,"name":"email_ids","in":"query"},{"schema":{"type":"string","description":"Comma-separated thread IDs, maximum 100."},"required":false,"name":"thread_ids","in":"query"},{"schema":{"type":"string","enum":["pending","final","canceled"]},"required":false,"name":"undo_status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","enum":["send_at","email_id","thread_id"]},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"sort_direction","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Submission list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxSubmissionCursorListResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/submissions/changes":{"get":{"operationId":"mailboxGetSubmissionChanges","summary":"Get submission changes","description":"Returns send submission changes since a prior submission state, or the current state when omitted.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Submission changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxChangesResponse"}}}},"400":{"description":"Invalid sync state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/submissions/{submission_id}":{"get":{"operationId":"mailboxGetSubmission","summary":"Get a mailbox submission","description":"Returns one send submission for the authenticated mailbox. Responses include a weak `ETag` header.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"submission_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Submission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxSubmissionResponse"}}}},"304":{"description":"Not modified"},"404":{"description":"Submission not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/quotas":{"get":{"operationId":"mailboxListQuotas","summary":"List mailbox quotas","description":"Returns a cursor-paginated list of quota usage and limits for the authenticated mailbox.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"name","in":"query"},{"schema":{"type":"string","enum":["account","domain","global"]},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","enum":["count","octets"]},"required":false,"name":"resource_type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["name","used"]},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"sort_direction","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Quota list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxQuotaCursorListResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/quotas/changes":{"get":{"operationId":"mailboxGetQuotaChanges","summary":"Get quota changes","description":"Returns quota changes since a prior quota state, or the current quota state when omitted.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Quota changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxChangesResponse"}}}},"400":{"description":"Invalid sync state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/usage":{"get":{"operationId":"mailboxListUsage","summary":"Get mailbox usage","description":"Returns a compact usage view derived from mailbox quota records. Responses include a weak `ETag` header.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Mailbox usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxUsageResponse"}}}},"304":{"description":"Not modified"}}}},"/mailbox/messages":{"get":{"operationId":"mailboxListMessages","summary":"List mailbox messages","description":"Returns a cursor-paginated list of messages for the authenticated mailbox. Requires Mailbox API access.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Filter to messages in this folder ID."},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string","description":"Filter to messages in this thread ID."},"required":false,"name":"thread_id","in":"query"},{"schema":{"type":"string","description":"Full-text search query across message fields."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by sender email address or display name."},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","description":"Filter by To recipient email address or display name."},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","description":"Filter by CC recipient email address or display name."},"required":false,"name":"cc","in":"query"},{"schema":{"type":"string","description":"Filter by BCC recipient email address or display name."},"required":false,"name":"bcc","in":"query"},{"schema":{"type":"string","description":"Filter by subject text."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Filter by message body text."},"required":false,"name":"body","in":"query"},{"schema":{"type":"string","description":"Header name to match with `header_value`."},"required":false,"name":"header_name","in":"query"},{"schema":{"type":"string","description":"Header value to match with `header_name`."},"required":false,"name":"header_value","in":"query"},{"schema":{"type":"integer","minimum":0,"description":"Minimum message size in bytes."},"required":false,"name":"min_size_bytes","in":"query"},{"schema":{"type":"integer","minimum":0,"description":"Maximum message size in bytes."},"required":false,"name":"max_size_bytes","in":"query"},{"schema":{"type":"string","description":"Require this message keyword, such as `$seen`."},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"string","description":"Exclude messages with this keyword."},"required":false,"name":"not_keyword","in":"query"},{"schema":{"type":"string","description":"Filter to messages after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Filter to messages before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean","description":"When true, only return messages with attachments."},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean","description":"When true, only return unread messages."},"required":false,"name":"is_unread","in":"query"},{"schema":{"type":"string","enum":["received_at","sent_at","subject","from","to","size_bytes"],"description":"Message field to sort by."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction."},"required":false,"name":"sort_direction","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Message list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMessageSummaryCursorListResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox API access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages/query-changes":{"get":{"operationId":"mailboxQueryMessageChanges","summary":"Get message query changes","description":"Returns filtered message-list index changes since a prior message query state, or the current message query state when omitted.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"since_query_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"up_to_id","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"calculate_total","in":"query"},{"schema":{"type":"string","description":"Filter to messages in this folder ID."},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string","description":"Full-text search query across message fields."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by sender email address or display name."},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","description":"Filter by To recipient email address or display name."},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","description":"Filter by CC recipient email address or display name."},"required":false,"name":"cc","in":"query"},{"schema":{"type":"string","description":"Filter by BCC recipient email address or display name."},"required":false,"name":"bcc","in":"query"},{"schema":{"type":"string","description":"Filter by subject text."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Filter by message body text."},"required":false,"name":"body","in":"query"},{"schema":{"type":"string","description":"Header name to match with `header_value`."},"required":false,"name":"header_name","in":"query"},{"schema":{"type":"string","description":"Header value to match with `header_name`."},"required":false,"name":"header_value","in":"query"},{"schema":{"type":"integer","minimum":0,"description":"Minimum message size in bytes."},"required":false,"name":"min_size_bytes","in":"query"},{"schema":{"type":"integer","minimum":0,"description":"Maximum message size in bytes."},"required":false,"name":"max_size_bytes","in":"query"},{"schema":{"type":"string","description":"Require this message keyword, such as `$seen`."},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"string","description":"Exclude messages with this keyword."},"required":false,"name":"not_keyword","in":"query"},{"schema":{"type":"string","description":"Filter to messages after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Filter to messages before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean","description":"When true, only return messages with attachments."},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean","description":"When true, only return unread messages."},"required":false,"name":"is_unread","in":"query"},{"schema":{"type":"string","enum":["received_at","sent_at","subject","from","to","size_bytes"]},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"sort_direction","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Message query changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMessageQueryChangesResponse"}}}},"400":{"description":"Invalid query sync state or filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages:batch-get":{"post":{"operationId":"mailboxBatchGetMessages","summary":"Batch get mailbox messages","description":"Returns exact messages by ID. Use `body_mode` to choose summary-only output, raw body output, or clean JSON content. Attachment output remains metadata only; attachment contents are not parsed.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxBatchGetBody"}}}},"responses":{"200":{"description":"Batch message result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxBatchGetResultResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}]}},"/mailbox/messages:batch-update":{"post":{"operationId":"mailboxBatchUpdateMessages","summary":"Batch update mailbox messages","description":"Updates allowed message flags and keywords for up to 100 messages with state-safe conflict handling.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.settings.update"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchUpdateMailboxMessagesBody"}}}},"responses":{"200":{"description":"Batch update result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxBatchUpdateMessagesResultResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}]}},"/mailbox/messages:batch-delete":{"post":{"operationId":"mailboxBatchDeleteMessages","summary":"Batch delete mailbox messages","description":"Moves up to 100 messages to Trash by default with state-safe conflict handling. Set `permanent=true` to permanently delete them.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.settings.update"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchDeleteMailboxMessagesBody"}}}},"responses":{"200":{"description":"Batch delete result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxBatchDeleteMessagesResultResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}]}},"/mailbox/messages/count":{"get":{"operationId":"mailboxCountMessages","summary":"Count mailbox messages","description":"Returns a count for the supplied mailbox message filters without returning message rows.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Filter to messages in this folder ID."},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string","description":"Filter to messages in this thread ID."},"required":false,"name":"thread_id","in":"query"},{"schema":{"type":"string","description":"Full-text search query across message fields."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by sender email address or display name."},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","description":"Filter by To recipient email address or display name."},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","description":"Filter by CC recipient email address or display name."},"required":false,"name":"cc","in":"query"},{"schema":{"type":"string","description":"Filter by BCC recipient email address or display name."},"required":false,"name":"bcc","in":"query"},{"schema":{"type":"string","description":"Filter by subject text."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Filter by message body text."},"required":false,"name":"body","in":"query"},{"schema":{"type":"string","description":"Header name to match with `header_value`."},"required":false,"name":"header_name","in":"query"},{"schema":{"type":"string","description":"Header value to match with `header_name`."},"required":false,"name":"header_value","in":"query"},{"schema":{"type":"integer","minimum":0,"description":"Minimum message size in bytes."},"required":false,"name":"min_size_bytes","in":"query"},{"schema":{"type":"integer","minimum":0,"description":"Maximum message size in bytes."},"required":false,"name":"max_size_bytes","in":"query"},{"schema":{"type":"string","description":"Require this message keyword, such as `$seen`."},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"string","description":"Exclude messages with this keyword."},"required":false,"name":"not_keyword","in":"query"},{"schema":{"type":"string","description":"Filter to messages after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Filter to messages before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean","description":"When true, only return messages with attachments."},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean","description":"When true, only return unread messages."},"required":false,"name":"is_unread","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Message count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMessageCountResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages/search-snippets":{"get":{"operationId":"mailboxSearchMessageSnippets","summary":"Get message search snippets","description":"Returns subject and preview snippets for a text search. Provide `message_ids` to snippet exact messages, or omit it to snippet the first filtered results.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Filter to messages in this folder ID."},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string","description":"Filter by sender email address or display name."},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","description":"Filter by To recipient email address or display name."},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","description":"Filter by CC recipient email address or display name."},"required":false,"name":"cc","in":"query"},{"schema":{"type":"string","description":"Filter by BCC recipient email address or display name."},"required":false,"name":"bcc","in":"query"},{"schema":{"type":"string","description":"Filter by subject text."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Filter by message body text."},"required":false,"name":"body","in":"query"},{"schema":{"type":"string","description":"Header name to match with `header_value`."},"required":false,"name":"header_name","in":"query"},{"schema":{"type":"string","description":"Header value to match with `header_name`."},"required":false,"name":"header_value","in":"query"},{"schema":{"type":"integer","minimum":0,"description":"Minimum message size in bytes."},"required":false,"name":"min_size_bytes","in":"query"},{"schema":{"type":"integer","minimum":0,"description":"Maximum message size in bytes."},"required":false,"name":"max_size_bytes","in":"query"},{"schema":{"type":"string","description":"Require this message keyword, such as `$seen`."},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"string","description":"Exclude messages with this keyword."},"required":false,"name":"not_keyword","in":"query"},{"schema":{"type":"string","description":"Filter to messages after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Filter to messages before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean","description":"When true, only return messages with attachments."},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean","description":"When true, only return unread messages."},"required":false,"name":"is_unread","in":"query"},{"schema":{"type":"string","description":"Search text used to generate snippets."},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","description":"Comma-separated message IDs, maximum 100."},"required":false,"name":"message_ids","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)."},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Search snippets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxSearchSnippetsResultResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/attachments:upload":{"post":{"operationId":"mailboxUploadAttachment","summary":"Upload a mailbox attachment","description":"Uploads one attachment as binary data and returns a blob ID that can be supplied to `POST /mailbox/messages/send`.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["email.send"]},{"bearerAuth":[]},{"oauth2":["mailbox.read","mailbox.drafts.write"]}],"parameters":[{"schema":{"type":"string","description":"Filename to use when sending the uploaded attachment."},"required":true,"name":"filename","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary","description":"Raw attachment bytes."}}}},"responses":{"200":{"description":"Attachment uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAttachmentUploadResultResponse"}}}},"400":{"description":"Invalid upload request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Attachment too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Mailbox service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/attachment-uploads":{"post":{"operationId":"mailboxCreateAttachmentUpload","summary":"Create a presigned mailbox attachment upload","description":"Creates a short-lived signed PUT URL for one attachment. The caller must be authenticated to mint the URL; the later PUT uses the signed URL, exact Content-Type, and exact Content-Length without sending a bearer token. The PUT returns a blob ID that can be supplied to `POST /mailbox/messages/send`.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["email.send"]},{"bearerAuth":[]},{"oauth2":["mailbox.read","mailbox.drafts.write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAttachmentUploadIntentBody"}}}},"responses":{"200":{"description":"Attachment upload URL created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAttachmentUploadIntentResultResponse"}}}},"400":{"description":"Invalid upload request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body or attachment too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Attachment uploads unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}]}},"/mailbox/messages/send":{"post":{"operationId":"mailboxSendMessage","summary":"Send a mailbox message","description":"Creates and queues a message from the authenticated mailbox. Supply an `Idempotency-Key` header to safely retry. Attachments may use small inline base64 content or blob IDs returned by `POST /mailbox/attachments:upload` or `POST /mailbox/attachment-uploads`.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["email.send"]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (mailbox, endpoint, key). Different body with same key returns 409 idempotency_conflict."},"required":false,"name":"Idempotency-Key","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMailboxMessageBody"}}}},"responses":{"200":{"description":"Message queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxSendResultResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Message validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Mailbox service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages/{message_id}":{"get":{"operationId":"mailboxGetMessage","summary":"Get a mailbox message","description":"Returns one message from the authenticated mailbox. Responses include a weak `ETag` header. When attachment metadata includes short-lived download URLs, a conditional request may return `200` even when the stable message ETag matches so the response can renew expired URLs.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Message ID."},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMessageDetailResponse"}}}},"304":{"description":"Not modified"},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"mailboxUpdateMessage","summary":"Update mailbox message flags","description":"Updates mutable message flags and keywords unconditionally unless `If-Match` is supplied. Send `If-Match` with a prior ETag to reject stale edits.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.settings.update"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchMailboxMessageBody"}}}},"responses":{"200":{"description":"Updated message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMessageDetailResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"ETag conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"mailboxDeleteMessage","summary":"Delete a mailbox message","description":"Moves a message to Trash by default, unconditionally unless `If-Match` is supplied. Set `permanent=true` to permanently delete it. Send `If-Match` with a prior ETag to reject stale deletes.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.settings.update"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"boolean"},"required":false,"name":"permanent","in":"query"},{"schema":{"type":"string"},"required":false,"name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMessageDeletedResponse"}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"ETag or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages/{message_id}/raw":{"get":{"operationId":"mailboxDownloadRawMessage","summary":"Download the original message","description":"Downloads the stored message as an .eml file, including its original headers, body and attachments. Requires access to the selected inbox. Supports conditional requests with If-None-Match.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Message ID."},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Original message file","headers":{"ETag":{"schema":{"type":"string"},"description":"Validator for the stored message."},"Content-Disposition":{"schema":{"type":"string"},"description":"Attachment filename."},"Content-Length":{"schema":{"type":"string"},"description":"Size of the stored message in bytes."}},"content":{"message/rfc822":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"Not modified"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox read permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Message download unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages/{message_id}/body":{"get":{"operationId":"mailboxListBody","summary":"Get raw message body","description":"Returns raw message body content for the authenticated mailbox. This endpoint does not strip signatures, strip quoted replies, extract links, or clean the body into a structured content shape.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Message ID."},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string","enum":["text","html","both"],"description":"Body part to return."},"required":false,"name":"part","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000000,"description":"Maximum body characters to return before truncation."},"required":false,"name":"max_body_chars","in":"query"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Raw message body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxRawBodyResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages/{message_id}/content":{"get":{"operationId":"mailboxListContent","summary":"Get clean message content","description":"Returns deterministic clean JSON content for one message. Attachment output is metadata only; attachment contents are not parsed by this endpoint.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Message ID."},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string","enum":["auto","text","html"],"description":"Body part to return. `auto` prefers text when available."},"required":false,"name":"part","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000000,"description":"Maximum body characters to return before truncation."},"required":false,"name":"max_body_chars","in":"query"},{"schema":{"type":"boolean","description":"When true, remove detected email signatures."},"required":false,"name":"strip_signature","in":"query"},{"schema":{"type":"boolean","description":"When true, remove quoted reply text."},"required":false,"name":"strip_quotes","in":"query"},{"schema":{"type":"boolean","description":"When true, include links extracted from the body."},"required":false,"name":"include_links","in":"query"},{"schema":{"type":"boolean","description":"When true, include HTML content when available."},"required":false,"name":"include_html","in":"query"},{"schema":{"type":"string","enum":["none","selected","full"],"description":"Header detail to include in the response."},"required":false,"name":"include_headers","in":"query"},{"schema":{"type":"string","enum":["none","metadata"],"description":"Attachment detail to include. Contents are not returned."},"required":false,"name":"include_attachments","in":"query"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Clean message content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMessageContentResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/threads":{"get":{"operationId":"mailboxListThreads","summary":"List mailbox threads","description":"Returns a cursor-paginated list of conversation threads for the authenticated mailbox. Filter by text, participant, folder, unread state, attachment presence, or date range.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Full-text search query across thread messages."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by participant email address or display name."},"required":false,"name":"participant","in":"query"},{"schema":{"type":"string","description":"Filter to threads with messages in this folder ID."},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string","description":"Filter to threads updated after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Filter to threads updated before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean","description":"When true, only return threads with attachments."},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean","description":"When true, only return threads with unread messages."},"required":false,"name":"is_unread","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction."},"required":false,"name":"sort_direction","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Thread list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxThreadSummaryCursorListResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox API access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/threads/{thread_id}":{"get":{"operationId":"mailboxGetThread","summary":"Get a mailbox thread","description":"Returns thread metadata, message IDs, participants, last message, unread count, and state for one conversation. Responses include a weak `ETag` header.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Thread ID."},"required":true,"name":"thread_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxThreadDetailResponse"}}}},"304":{"description":"Not modified"},"404":{"description":"Thread not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/threads/{thread_id}/messages":{"get":{"operationId":"mailboxListThreadMessages","summary":"List thread messages","description":"Returns cursor-paginated message summaries for one thread. Use the thread content endpoint when you need cleaned bodies.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Thread ID."},"required":true,"name":"thread_id","in":"path"},{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Message sort direction within the thread."},"required":false,"name":"sort","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Thread messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxThreadMessageSummaryCursorListResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Thread not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/threads/{thread_id}/content":{"get":{"operationId":"mailboxGetThreadContent","summary":"Get clean thread content","description":"Returns a cursor-paginated clean JSON view of messages in a thread. Attachment output is metadata only; attachment contents are not parsed by this endpoint.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"},{"schema":{"type":"string","enum":["auto","text","html"],"description":"Body part to return. `auto` prefers text when available."},"required":false,"name":"part","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000000,"description":"Maximum body characters to return before truncation."},"required":false,"name":"max_body_chars","in":"query"},{"schema":{"type":"boolean","description":"When true, remove detected email signatures."},"required":false,"name":"strip_signature","in":"query"},{"schema":{"type":"boolean","description":"When true, remove quoted reply text."},"required":false,"name":"strip_quotes","in":"query"},{"schema":{"type":"boolean","description":"When true, include links extracted from the body."},"required":false,"name":"include_links","in":"query"},{"schema":{"type":"boolean","description":"When true, include HTML content when available."},"required":false,"name":"include_html","in":"query"},{"schema":{"type":"string","enum":["none","selected","full"],"description":"Header detail to include in the response."},"required":false,"name":"include_headers","in":"query"},{"schema":{"type":"string","enum":["none","metadata"],"description":"Attachment detail to include. Contents are not returned."},"required":false,"name":"include_attachments","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Clean thread content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxThreadContentResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Thread not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages/{message_id}/attachments/{attachment_id}":{"get":{"operationId":"mailboxGetMessageAttachment","summary":"Download a message attachment","description":"Streams one attachment from a message through the authenticated endpoint. Attachment metadata also provides short-lived download URLs for clients that cannot set request headers. Supports standard byte ranges.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"attachment_id","in":"path"},{"schema":{"type":"string","description":"Optional byte range, for example `bytes=0-1048575`."},"required":false,"name":"Range","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."},{"schema":{"type":"string","description":"Short-lived token embedded in attachment metadata `download_url` values. Clients normally fetch the full URL rather than constructing this parameter manually."},"required":false,"name":"download_token","in":"query"}],"responses":{"200":{"description":"Attachment bytes"},"206":{"description":"Partial attachment bytes"},"400":{"description":"Invalid range header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Attachment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/folders":{"get":{"operationId":"mailboxListFolders","summary":"List mailbox folders","description":"Returns a cursor-paginated list of folders for the authenticated mailbox.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)."},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Folder list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxFolderCursorListResponse"}}}}}},"post":{"operationId":"mailboxCreateFolder","summary":"Create a mailbox folder","description":"Creates a folder in the authenticated mailbox.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.settings.update"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMailboxFolderBody"}}}},"responses":{"201":{"description":"Folder created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxFolderResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Folder validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}]}},"/mailbox/folders/changes":{"get":{"operationId":"mailboxGetFolderChanges","summary":"Get folder changes","description":"Returns folder changes since a prior folder state, or the current folder state when omitted.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Folder changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxChangesResponse"}}}},"400":{"description":"Invalid sync state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/folders/query-changes":{"get":{"operationId":"mailboxQueryFolderChanges","summary":"Get folder query changes","description":"Returns folder-list index changes since a prior folder query state, or the current folder query state when omitted.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"since_query_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Folder query changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxFolderQueryChangesResponse"}}}},"400":{"description":"Invalid query sync state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/folders/{folder_id}":{"get":{"operationId":"mailboxGetFolder","summary":"Get a mailbox folder","description":"Returns one folder from the authenticated mailbox. Responses include a weak `ETag` header.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"folder_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxFolderResponse"}}}},"304":{"description":"Not modified"},"404":{"description":"Folder not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"mailboxUpdateFolder","summary":"Update a mailbox folder","description":"Updates a folder unconditionally unless `If-Match` is supplied. Send `If-Match` with a prior ETag to reject stale edits.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.settings.update"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"folder_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchMailboxFolderBody"}}}},"responses":{"200":{"description":"Updated folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxFolderResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Folder not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"ETag conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"mailboxDeleteFolder","summary":"Delete a mailbox folder","description":"Deletes an empty custom folder unconditionally unless `If-Match` is supplied. Built-in folders and non-empty folders cannot be deleted. Send `If-Match` with a prior ETag to reject stale deletes.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.settings.update"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"folder_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxFolderDeletedResponse"}}}},"409":{"description":"Folder cannot be deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/changes":{"get":{"operationId":"mailboxGetChanges","summary":"Get mailbox changes","description":"Returns message changes in the legacy shape when `types` is omitted. Pass a comma-separated `types` list for a typed state map.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Legacy message state cursor to resume from."},"required":false,"name":"since_state","in":"query"},{"schema":{"type":"string","description":"Comma-separated list: messages, folders, threads, submissions, identities, quotas."},"required":false,"name":"types","in":"query"},{"schema":{"type":"string","description":"Message state cursor to resume from."},"required":false,"name":"messages_since_state","in":"query"},{"schema":{"type":"string","description":"Folder state cursor to resume from."},"required":false,"name":"folders_since_state","in":"query"},{"schema":{"type":"string","description":"Thread state cursor to resume from."},"required":false,"name":"threads_since_state","in":"query"},{"schema":{"type":"string","description":"Submission state cursor to resume from."},"required":false,"name":"submissions_since_state","in":"query"},{"schema":{"type":"string","description":"Identity state cursor to resume from."},"required":false,"name":"identities_since_state","in":"query"},{"schema":{"type":"string","description":"Quota state cursor to resume from."},"required":false,"name":"quotas_since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"description":"Maximum change records to return (default 50, max 500)."},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Mailbox changes","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/MailboxChangesResponse"},{"$ref":"#/components/schemas/MailboxTypedChangesResponse"}]}}}},"400":{"description":"Invalid sync state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/events":{"get":{"operationId":"mailboxStreamEvents","summary":"Stream mailbox events","description":"Streams bounded rich mailbox events for connected clients. Each received-message event includes subject, participants, preview, attachment metadata, and a capped body snapshot; use the message endpoints for full content or attachment bytes.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Select a granted mailbox when using an OAuth token with multiple mailboxes."},"required":false,"name":"mailbox_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated list: message.received, message.received.spam."},"required":false,"name":"event_types","in":"query"},{"schema":{"type":"string"},"required":false,"name":"last_event_id","in":"query"},{"schema":{"type":"integer","minimum":10,"maximum":300},"required":false,"name":"ping","in":"query"},{"schema":{"type":"integer","minimum":30,"maximum":3600},"required":false,"name":"close_after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"Last-Event-ID","in":"header"}],"responses":{"200":{"description":"Server-sent event stream. Event data uses the MailboxRealtimeEvent shape.","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/MailboxRealtimeEvent"}}}},"400":{"description":"Invalid stream parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Mailbox API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many realtime connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Realtime events unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/calendars":{"get":{"operationId":"mailboxListCalendars","tags":["Mailbox API"],"summary":"List calendars","security":[{"bearerAuth":[]},{"oauth2":["calendar.read"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum records per page, up to 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Cursor from the previous page. Keep the same filters while paging."},"required":false,"name":"cursor","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Calendars.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarListResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"mailboxCreateCalendar","tags":["Mailbox API"],"summary":"Create a private calendar","security":[{"bearerAuth":[]},{"oauth2":["calendar.write"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Stable key for this exact create in this mailbox. Saved responses replay for 24 hours. Uncertain creates still require read-only reconciliation."},"required":false,"name":"Idempotency-Key","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCalendarBody"}}}},"responses":{"201":{"description":"Calendar created.","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarCreatedResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/calendars/{calendar_id}":{"get":{"operationId":"mailboxGetCalendar","tags":["Mailbox API"],"summary":"Get a calendar","security":[{"bearerAuth":[]},{"oauth2":["calendar.read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Calendar ID in the selected mailbox."},"required":true,"name":"calendar_id","in":"path"},{"schema":{"type":"string","description":"ETag from a previous resource GET; a matching version returns 304."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Calendar.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current resource version."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarResponse"}}}},"304":{"description":"Unchanged.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current resource version."}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"mailboxDeleteCalendar","tags":["Mailbox API"],"summary":"Delete an empty calendar","description":"Fetch the calendar and supply its ETag in If-Match. A calendar containing events returns 409 conflict.","security":[{"bearerAuth":[]},{"oauth2":["calendar.write"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Calendar ID in the selected mailbox."},"required":true,"name":"calendar_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"ETag from the most recent calendar GET. Wildcards are rejected."},"required":true,"name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Calendar deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarDeletedResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/calendar-events":{"get":{"operationId":"mailboxListCalendarEvents","tags":["Mailbox API"],"summary":"List calendar events","description":"UID search is eventually consistent. An empty immediate lookup leaves an uncertain create unresolved and never authorises repeating it.","security":[{"bearerAuth":[]},{"oauth2":["calendar.read"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum records per page, up to 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Cursor from the previous page. Keep the same filters while paging."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Exact immutable event UID. Empty results can reflect a recent create awaiting search visibility; never repeat an uncertain create."},"required":false,"name":"uid","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Limit events to this calendar in the selected mailbox."},"required":false,"name":"calendar_id","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarEventListResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"mailboxCreateCalendarEvent","tags":["Mailbox API"],"summary":"Create a non-sending event","description":"Creates one event without participants, recurrence or alerts. Invitations and scheduling messages are disabled. Retain UID before dispatch. If creation is uncertain, use read-only UID lookup; do not repeat the create.","security":[{"bearerAuth":[]},{"oauth2":["calendar.write"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Stable key for this exact create in this mailbox. Saved responses replay for 24 hours. Uncertain creates still require read-only reconciliation."},"required":false,"name":"Idempotency-Key","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCalendarEventBody"}}}},"responses":{"201":{"description":"Event identity acknowledged. Fetch it using the Location header.","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarEventCreatedResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/calendar-events/{event_id}":{"get":{"operationId":"mailboxGetCalendarEvent","tags":["Mailbox API"],"summary":"Get a calendar event","security":[{"bearerAuth":[]},{"oauth2":["calendar.read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Event ID in the selected mailbox."},"required":true,"name":"event_id","in":"path"},{"schema":{"type":"string","description":"ETag from a previous resource GET; a matching version returns 304."},"required":false,"name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Event.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current resource version."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarEventResponse"}}}},"304":{"description":"Unchanged.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current resource version."}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"mailboxUpdateCalendarEvent","tags":["Mailbox API"],"summary":"Update a non-sending event","security":[{"bearerAuth":[]},{"oauth2":["calendar.write"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Event ID in the selected mailbox."},"required":true,"name":"event_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"ETag from the most recent event GET. Wildcards are rejected."},"required":true,"name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchCalendarEventBody"}}}},"responses":{"200":{"description":"Update acknowledged. Fetch the event for its current version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarEventUpdatedResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"mailboxDeleteCalendarEvent","tags":["Mailbox API"],"summary":"Delete a non-sending event","security":[{"bearerAuth":[]},{"oauth2":["calendar.write"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Event ID in the selected mailbox."},"required":true,"name":"event_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"ETag from the most recent event GET. Wildcards are rejected."},"required":true,"name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Event deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarEventDeletedResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/calendar-events/changes":{"get":{"operationId":"mailboxGetCalendarEventChanges","tags":["Mailbox API"],"summary":"Get calendar event changes","description":"Coalesced changes for synchronisation, not a lossless mutation history. Missing or expired state requires a full list refresh; establish a new baseline before listing and then consume changes to cover concurrent edits.","security":[{"bearerAuth":[]},{"oauth2":["calendar.read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$","description":"Event state from the previous changes response. Omit to establish a full-refresh baseline."},"required":false,"name":"since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100,"description":"Maximum changed IDs across the response, up to 100."},"required":false,"name":"limit","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Changes or an explicit full refresh requirement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCalendarChangesResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/drafts":{"get":{"operationId":"mailboxListDrafts","tags":["Mailbox API"],"summary":"List saved drafts","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size; default 50, maximum 100."},"required":false,"description":"Page size; default 50, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor returned by the previous page."},"required":false,"description":"Cursor returned by the previous page.","name":"cursor","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Saved drafts, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDraftListResponse"}}}},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"mailboxCreateDraft","tags":["Mailbox API"],"summary":"Create a saved draft","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read","mailbox.drafts.write"]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Reuse this key when retrying the same create request."},"required":false,"description":"Reuse this key when retrying the same create request.","name":"Idempotency-Key","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMailboxDraft"}}}},"responses":{"201":{"description":"Saved draft and its revision.","headers":{"Location":{"schema":{"type":"string"},"description":"Canonical draft URL."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDraftResponse"}}}},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/drafts/{draftId}/send":{"post":{"operationId":"mailboxSendDraft","tags":["Mailbox API"],"summary":"Send a saved draft revision","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read","email.send"]}],"parameters":[{"schema":{"type":"string","description":"Stable draft ID."},"required":true,"description":"Stable draft ID.","name":"draftId","in":"path"},{"schema":{"type":"string","description":"Current draft ETag; expected_revision is required."},"required":false,"description":"Current draft ETag; expected_revision is required.","name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMailboxDraft"}}}},"responses":{"200":{"description":"Saved draft and its revision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDraftResponse"}}}},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/drafts/{draftId}":{"delete":{"operationId":"mailboxDeleteDraft","tags":["Mailbox API"],"summary":"Delete a saved draft","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read","mailbox.drafts.write"]}],"parameters":[{"schema":{"type":"string","description":"Stable draft ID."},"required":true,"description":"Stable draft ID.","name":"draftId","in":"path"},{"schema":{"type":"string","description":"Delete only if this is still the current draft."},"required":false,"description":"Delete only if this is still the current draft.","name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Deletion recorded; removal finishes in the background. A send already in progress cannot be deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDraftDeleteResponse"}}}},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"mailboxGetDraft","tags":["Mailbox API"],"summary":"Read a saved draft","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Stable draft ID."},"required":true,"description":"Stable draft ID.","name":"draftId","in":"path"},{"schema":{"type":"string","description":"Return 304 if this draft has not changed."},"required":false,"description":"Return 304 if this draft has not changed.","name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Saved draft and its revision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDraftResponse"}}}},"304":{"description":"Draft has not changed."},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"mailboxUpdateDraft","tags":["Mailbox API"],"summary":"Edit a saved draft","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read","mailbox.drafts.write"]}],"parameters":[{"schema":{"type":"string","description":"Stable draft ID."},"required":true,"description":"Stable draft ID.","name":"draftId","in":"path"},{"schema":{"type":"string","description":"Current draft ETag; expected_revision is also required."},"required":false,"description":"Current draft ETag; expected_revision is also required.","name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMailboxDraft"}}}},"responses":{"200":{"description":"Saved draft and its revision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDraftResponse"}}}},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/drafts/{draftId}/schedule":{"patch":{"operationId":"mailboxControlDraftSchedule","tags":["Mailbox API"],"summary":"Reschedule or cancel a saved draft send","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read","email.send"]}],"parameters":[{"schema":{"type":"string","description":"Stable draft ID."},"required":true,"description":"Stable draft ID.","name":"draftId","in":"path"},{"schema":{"type":"string","description":"Current draft ETag; both revision and schedule version remain required."},"required":false,"description":"Current draft ETag; both revision and schedule version remain required.","name":"If-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlMailboxDraftSchedule"}}}},"responses":{"200":{"description":"Saved draft and its revision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDraftResponse"}}}},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/messages/{message_id}/attachments/{attachment_id}/text":{"post":{"operationId":"mailboxRequestAttachmentText","tags":["Mailbox API"],"summary":"Request attachment text","description":"Extract readable text from an attachment up to 7500000 bytes, at no extra charge. Repeating this request reuses the same current source extraction for 24 hours; no request body or Idempotency-Key is needed. Conversion runs for at most 30 seconds. OCR is unavailable. Current mailbox access and the source attachment are checked before serving cached text. If extraction cannot complete, use the original attachment download.","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Message ID in the selected mailbox."},"required":true,"description":"Message ID in the selected mailbox.","name":"message_id","in":"path"},{"schema":{"type":"string","description":"Attachment ID from that message."},"required":true,"description":"Attachment ID from that message.","name":"attachment_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":1048576,"description":"Maximum UTF-8 text bytes returned. Default 262144; maximum 1048576. Applies to cached results too."},"required":false,"description":"Maximum UTF-8 text bytes returned. Default 262144; maximum 1048576. Applies to cached results too.","name":"max_bytes","in":"query"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Conversion completed. Check outcome before using text; original attachment downloads remain available.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current response validator, returned by GET."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAttachmentTextResponse"},"examples":{"ready":{"value":{"ok":true,"data":{"id":"ext_example","status":"complete","outcome":"ready","text":"# Invoice\nAmount: $25","format":"markdown","truncated":false,"expires_at":"2026-09-30T00:00:00.000Z"},"meta":{"request_id":"req_example"}}},"unsupported":{"value":{"ok":true,"data":{"id":"ext_example","status":"complete","outcome":"unsupported","text":"","format":"markdown","truncated":false,"expires_at":"2026-09-30T00:00:00.000Z"},"meta":{"request_id":"req_example"}}}}}}},"202":{"description":"Extraction is pending or running. Poll GET on this same URL.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current response validator, returned by GET."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAttachmentTextResponse"},"example":{"ok":true,"data":{"id":"ext_example","status":"pending","outcome":null,"text":null,"format":"markdown","truncated":false,"expires_at":"2026-09-30T00:00:00.000Z"},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Source attachment or unexpired extraction not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"mailboxGetAttachmentText","tags":["Mailbox API"],"summary":"Read attachment text","description":"Read or poll a requested extraction. Returns 404 after cache expiry or source removal. Current access and source availability are checked even with If-None-Match. This request does not start a conversion.","security":[{"bearerAuth":[]},{"oauth2":["mailbox.read"]}],"parameters":[{"schema":{"type":"string","description":"Message ID in the selected mailbox."},"required":true,"description":"Message ID in the selected mailbox.","name":"message_id","in":"path"},{"schema":{"type":"string","description":"Attachment ID from that message."},"required":true,"description":"Attachment ID from that message.","name":"attachment_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":1048576,"description":"Maximum UTF-8 text bytes returned. Default 262144; maximum 1048576. Applies to cached results too."},"required":false,"description":"Maximum UTF-8 text bytes returned. Default 262144; maximum 1048576. Applies to cached results too.","name":"max_bytes","in":"query"},{"schema":{"type":"string","description":"Return 304 when the authorised response is unchanged."},"required":false,"description":"Return 304 when the authorised response is unchanged.","name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Conversion completed. Check outcome before using text; original attachment downloads remain available.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current response validator, returned by GET."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAttachmentTextResponse"},"examples":{"ready":{"value":{"ok":true,"data":{"id":"ext_example","status":"complete","outcome":"ready","text":"# Invoice\nAmount: $25","format":"markdown","truncated":false,"expires_at":"2026-09-30T00:00:00.000Z"},"meta":{"request_id":"req_example"}}},"unsupported":{"value":{"ok":true,"data":{"id":"ext_example","status":"complete","outcome":"unsupported","text":"","format":"markdown","truncated":false,"expires_at":"2026-09-30T00:00:00.000Z"},"meta":{"request_id":"req_example"}}}}}}},"202":{"description":"Extraction is pending or running. Poll GET on this same URL.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current response validator, returned by GET."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxAttachmentTextResponse"},"example":{"ok":true,"data":{"id":"ext_example","status":"pending","outcome":null,"text":null,"format":"markdown","truncated":false,"expires_at":"2026-09-30T00:00:00.000Z"},"meta":{"request_id":"req_example"}}}}},"304":{"description":"Extraction response has not changed.","headers":{"ETag":{"schema":{"type":"string"},"description":"Current response validator, returned by GET."}}},"400":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Source attachment or unexpired extraction not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailbox/sender-choices":{"get":{"operationId":"mailboxGetSenderChoices","summary":"Get permitted sender choices","description":"Intersects current team, inbox and credential policies with provider restrictions and selected delivery groups. Subdomains require separate authorisation. Sending checks these permissions again before submission.","tags":["Mailbox API"],"security":[{"bearerAuth":[]},{"oauth2":["email.send"]}],"parameters":[{"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":50,"description":"Restrict choices to these delivery groups."},"required":false,"description":"Restrict choices to these delivery groups.","name":"delivery_group_id","in":"query"},{"schema":{"type":"string","description":"Return 304 when this ETag still matches."},"required":false,"description":"Return 304 when this ETag still matches.","name":"If-None-Match","in":"header"},{"name":"mailbox_id","in":"query","required":false,"schema":{"type":"string"},"description":"Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox."}],"responses":{"200":{"description":"Current permitted choices.","headers":{"ETag":{"description":"Current choices version.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxSenderChoicesResponse"}}}},"304":{"description":"Choices are unchanged.","headers":{"ETag":{"description":"Current choices version.","schema":{"type":"string"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mailboxes/{public_id}/filters":{"get":{"operationId":"managementGetMailboxFilters","summary":"Get mailbox sender filters","description":"Returns the current sender-filter mode and rule set for a mailbox. Mailbox-scoped rules override any domain-wide rules set on the parent domain.\n\nResponses carry a weak `ETag` — send it as `If-None-Match` to skip the body when the filter set has not changed (returns `304 Not Modified`). The same ETag is the value to use in `If-Match` on the corresponding PUT for optimistic concurrency.","tags":["Mailbox Filters"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Filter state","headers":{"ETag":{"description":"Weak ETag for conditional GETs and optimistic-concurrency PUTs.","schema":{"type":"string","example":"W/\"a1b2c3d4e5f60718\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterStateResponse"}}}},"304":{"description":"Not Modified — the client's cached copy (matching `If-None-Match`) is still current.","headers":{"ETag":{"description":"Current weak ETag.","schema":{"type":"string"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Filter service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"put":{"operationId":"managementSetMailboxFilters","summary":"Replace mailbox sender filters","description":"Atomically replaces the sender-filter mode and rule set for a mailbox. The entire rule set is swapped in a single operation — there is no intermediate state where the mailbox has a partial ruleset. A maximum of 1000 rules per request is enforced.\n\nFor optimistic concurrency, send `If-Match: <etag>` using the ETag from a prior GET. A mismatched `If-Match` returns `409 conflict` (the server's ETag is echoed back so you can decide whether to re-fetch). Responses carry the new ETag so chained edits can pipeline without a re-GET.","tags":["Mailbox Filters"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Mailbox public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs."},"required":false,"name":"If-Match","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFilterStateBody"}}}},"responses":{"200":{"description":"Updated filter state","headers":{"ETag":{"description":"Weak ETag for the post-update resource.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterStateResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`If-Match` ETag does not match the server's current version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Rule cap exceeded or invalid rule pattern","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Filter service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/domains/{public_id}/filters":{"get":{"operationId":"managementGetDomainFilters","summary":"Get domain-wide sender filters","description":"Returns the current sender-filter mode and rule set applied to every mailbox under this domain. Only sending and receiving domains support domain-wide filters. Per-mailbox rules take precedence at match time.\n\nResponses carry a weak `ETag` — send it as `If-None-Match` to skip the body when the filter set has not changed (returns `304 Not Modified`). The same ETag is the value to use in `If-Match` on the corresponding PUT for optimistic concurrency.","tags":["Domain Filters"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Domain public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Filter state","headers":{"ETag":{"description":"Weak ETag for conditional GETs and optimistic-concurrency PUTs.","schema":{"type":"string","example":"W/\"a1b2c3d4e5f60718\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterStateResponse"}}}},"304":{"description":"Not Modified — the client's cached copy (matching `If-None-Match`) is still current.","headers":{"ETag":{"description":"Current weak ETag.","schema":{"type":"string"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Domain is send-only and does not support inbound filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Filter service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"put":{"operationId":"managementSetDomainFilters","summary":"Replace domain-wide sender filters","description":"Atomically replaces the sender-filter mode and rule set for an entire sending and receiving domain. Applies to every mailbox under the domain unless that mailbox has its own per-mailbox rules (which take precedence). Maximum 1000 rules per request.\n\nFor optimistic concurrency, send `If-Match: <etag>` using the ETag from a prior GET. A mismatched `If-Match` returns `409 conflict` (the server's ETag is echoed back so you can decide whether to re-fetch). Responses carry the new ETag so chained edits can pipeline without a re-GET.","tags":["Domain Filters"],"security":[{"bearerAuth":[]},{"oauth2":["mailbox.admin.manage"]}],"parameters":[{"schema":{"type":"string","description":"Domain public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs."},"required":false,"name":"If-Match","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFilterStateBody"}}}},"responses":{"200":{"description":"Updated filter state","headers":{"ETag":{"description":"Weak ETag for the post-update resource.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterStateResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`If-Match` ETag does not match the server's current version, the domain is send-only, or deletion is in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Rule cap exceeded or invalid rule pattern","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Filter service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/inboxes/logs":{"get":{"operationId":"managementListInboxLogs","summary":"List incoming logs","description":"Returns paginated incoming message logs for billing accountability.","tags":["Inboxes"],"security":[{"bearerAuth":[]},{"oauth2":["logs.read"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max results (default 25)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor from previous page"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Filter by mailbox public ID"},"required":false,"name":"mailbox_id","in":"query"},{"schema":{"type":"string","enum":["message.received","message.received.spam"]},"required":false,"name":"event_type","in":"query"},{"schema":{"type":"string","description":"ISO 8601 start date. Date-only values start at 00:00 UTC."},"required":false,"name":"from_date","in":"query"},{"schema":{"type":"string","description":"ISO 8601 end date. Date-only values include the full UTC day."},"required":false,"name":"to_date","in":"query"},{"schema":{"type":"string","description":"Search mailbox, sender, recipient, subject, or message ID"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"Incoming log list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingLogItemCursorListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/inboxes/logs/{public_id}":{"get":{"operationId":"managementGetInboxLog","summary":"Get incoming log","description":"Returns one incoming message log by public ID.","tags":["Inboxes"],"security":[{"bearerAuth":[]},{"oauth2":["logs.read"]}],"parameters":[{"schema":{"type":"string","description":"Incoming log public ID (ilog_...)"},"required":true,"name":"public_id","in":"path"}],"responses":{"200":{"description":"Incoming log detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingLogItemResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/webhooks":{"get":{"operationId":"managementListWebhooks","summary":"List webhook subscriptions","description":"Returns a cursor-paginated list of webhook subscriptions configured for the team, ordered by `created_at` descending. The signing secret is never included. Pass `cursor=<next_cursor>` from the previous response to fetch the next page.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.read"]}],"parameters":[{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 50, max 100)"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Subscription list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionCursorListResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"managementCreateWebhook","summary":"Create a webhook subscription","description":"Creates a new webhook subscription and returns the signing secret ONCE in the response body. Store it securely — it cannot be retrieved later. Use `POST /webhooks/{id}/rotate-secret` to issue a new one.\n\nSupply an `Idempotency-Key` header (any unique string, max 255 chars) to safely retry on network errors. Replays with the same key return the original response; replays with a different body return `409 idempotency_conflict`.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.create"]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.","example":"webhooks-create-20260424-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateBody"}}}},"responses":{"201":{"description":"Subscription created, including the signing secret. The response carries a `Location` header pointing at the canonical GET URL for the new subscription.","headers":{"Location":{"description":"Canonical GET URL for the newly created webhook subscription.","schema":{"type":"string","example":"/api/v1/webhooks/whk_clxxxxxxxxxxxxxxxxxxxxxxxxx"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionWithSecretResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`Idempotency-Key` was replayed with a different body (`idempotency_conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed (e.g. non-https URL, unknown event type)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/webhooks/{public_id}":{"get":{"operationId":"managementGetWebhook","summary":"Get a webhook subscription","description":"Returns a single webhook subscription. The signing secret is never included. Responses carry a weak `ETag` header — send it back as `If-None-Match` on the next request and the server will return `304 Not Modified` (no body) when the resource has not changed. The same ETag is the value to use in `If-Match` on PATCH for optimistic concurrency.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.read"]}],"parameters":[{"schema":{"type":"string","description":"Webhook public ID","example":"whk_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a previous response. Returns 304 when unchanged."},"required":false,"name":"If-None-Match","in":"header"}],"responses":{"200":{"description":"Subscription","headers":{"ETag":{"description":"Weak ETag for conditional GETs and optimistic-concurrency PATCHes.","schema":{"type":"string","example":"W/\"a1b2c3d4e5f60718\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionResponse"}}}},"304":{"description":"Not Modified — the client's cached copy (matching `If-None-Match`) is still current.","headers":{"ETag":{"description":"Current weak ETag (same as request's `If-None-Match`).","schema":{"type":"string"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"managementUpdateWebhook","summary":"Update a webhook subscription","description":"Updates the URL, event types, or enabled flag. Any field omitted from the request body is left unchanged. The signing secret is unaffected — use `POST /webhooks/{id}/rotate-secret` to rotate it.\n\nFor optimistic concurrency, send `If-Match: <etag>` using the ETag from a prior GET. A mismatched `If-Match` returns `409 conflict` (the server's ETag is echoed back so you can decide whether to re-fetch). Responses carry the new ETag so chained edits can pipeline without a re-GET.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.update"]}],"parameters":[{"schema":{"type":"string","description":"Webhook public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs."},"required":false,"name":"If-Match","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdateBody"}}}},"responses":{"200":{"description":"Updated subscription","headers":{"ETag":{"description":"Weak ETag for the post-update resource.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`If-Match` ETag does not match the server's current version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed (e.g. non-https URL, unknown event type, empty event list)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"managementDeleteWebhook","summary":"Delete a webhook subscription","description":"Permanently removes the subscription. In-flight retries are dropped.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.delete"]}],"parameters":[{"schema":{"type":"string","description":"Webhook public ID"},"required":true,"name":"public_id","in":"path"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeletedResponse"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/webhooks/{public_id}/deliveries":{"get":{"operationId":"managementListDelivery","summary":"List webhook delivery attempts","description":"Returns recent delivery attempts for one webhook subscription, ordered by `created_at` descending. Delivery metadata is retained for 7 days. Use the payload endpoint while `payload_available` is true to inspect the exact JSON request body that was delivered.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.read"]}],"parameters":[{"schema":{"type":"string","description":"Webhook public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Pagination cursor — the `next_cursor` from the previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum results (default 25, max 100)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["message.delivered","message.bounced","message.complained","message.rejected","message.delivery_delayed","message.received","message.received.spam","calendar.changed","sendmux.test"],"description":"Filter by event type.","example":"message.bounced"},"required":false,"name":"event_type","in":"query"},{"schema":{"type":"string","enum":["success","retrying","failed","permanent_failure"],"description":"Filter by delivery result."},"required":false,"name":"result","in":"query"}],"responses":{"200":{"description":"Delivery-attempt list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryAttemptCursorListResponse"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/webhooks/{public_id}/deliveries/{delivery_id}/payload":{"get":{"operationId":"managementGetDeliveryPayload","summary":"Get a webhook delivery payload","description":"Returns the retained JSON request body for one delivery attempt. Payloads are retained for 7 days and may no longer be available after `payload_expires_at`.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.read"]}],"parameters":[{"schema":{"type":"string","description":"Webhook public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","description":"Delivery-attempt public ID"},"required":true,"name":"delivery_id","in":"path"}],"responses":{"200":{"description":"Delivery payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryPayloadResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Delivery not found or payload no longer available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/webhooks/{public_id}/rotate-secret":{"post":{"operationId":"managementRotateWebhookSecret","summary":"Rotate the signing secret","description":"Generates a fresh signing secret and returns it ONCE. The old secret is immediately invalidated — the next event delivery is signed with the new secret. Store the new value securely; it cannot be retrieved later.\n\nSupply an `Idempotency-Key` header to safely retry on network errors — replays under the same key return the original rotation response rather than minting a fresh secret. Replays against a different `public_id` under the same key return `409 idempotency_conflict`.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.manage"]}],"parameters":[{"schema":{"type":"string","description":"Webhook public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different target `public_id` under the same key returns 409 idempotency_conflict.","example":"webhooks-rotate-20260424-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Subscription with new signing secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionWithSecretResponse"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`Idempotency-Key` was replayed against a different webhook (`idempotency_conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/webhooks/{public_id}/test":{"post":{"operationId":"managementTestWebhook","summary":"Send a synthetic test event","description":"Publishes a synthetic `sendmux.test` event to this webhook subscription. The subscription must include `\"sendmux.test\"` in `event_types`, and mailbox filters do not block the test delivery. Returns the generated `event_id` so you can correlate the `X-Qubrics-Event-Id` or `X-Sendmux-Event-Id` header on your endpoint.\n\nSupply an `Idempotency-Key` header to safely retry on network errors — replays under the same key return the original `event_id` rather than publishing a second test event.","tags":["Webhooks"],"security":[{"bearerAuth":[]},{"oauth2":["webhook.manage"]}],"parameters":[{"schema":{"type":"string","description":"Webhook public ID"},"required":true,"name":"public_id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different target `public_id` under the same key returns 409 idempotency_conflict.","example":"webhooks-test-20260424-001"},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Test event published","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/WebhookTestResponse"}},"required":["data"]}],"unevaluatedProperties":false}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`Idempotency-Key` was replayed against a different webhook (`idempotency_conflict`) or the webhook is not subscribed to `sendmux.test` (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Event publish service is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"webhooks":{}}