{"openapi":"3.1.0","info":{"title":"Sendmux API","version":"1.0.0","description":"Programmatic access to your Sendmux email infrastructure."},"servers":[{"url":"https://app.sendmux.ai/api/v1","description":"API v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Sendmux 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."}},"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},"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"},"delete":{"type":"boolean"},"activate":{"type":"boolean"},"deactivate":{"type":"boolean"},"test":{"type":"boolean"}},"required":["update","delete","activate","deactivate","test"],"additionalProperties":false},"ProviderQuotaRange":{"type":["object","null"],"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":{"$ref":"#/components/schemas/ProviderQuotaRange"},"per_minute":{"$ref":"#/components/schemas/ProviderQuotaRange"},"per_hour":{"$ref":"#/components/schemas/ProviderQuotaRange"},"per_day":{"$ref":"#/components/schemas/ProviderQuotaRange"}},"required":["per_second","per_minute","per_hour","per_day"],"additionalProperties":false},"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."},"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/ProviderItem"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":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","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},{"allOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"object"}]},{"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},{"allOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"object"}]},{"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},{"allOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"object"}]},{"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},{"allOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"object"}]},{"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"}},"required":["name","smtp_host","smtp_port","smtp_protocol","smtp_username","smtp_password"],"additionalProperties":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","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},{"allOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"object"}]},{"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},{"allOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"object"}]},{"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},{"allOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"object"}]},{"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},{"allOf":[{"$ref":"#/components/schemas/ProviderQuotaRange"},{"type":"object"}]},{"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"},"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},"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},"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},"SharedAmazonSesLimitRequest":{"type":["object","null"],"properties":{"id":{"type":"string","example":"slir_clxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","enum":["pending","approved","denied"]},"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},"SharedAmazonSesLimitRequestPage":{"type":"object","properties":{"limit":{"$ref":"#/components/schemas/SharedAmazonSesLimit"},"pending_request":{"$ref":"#/components/schemas/SharedAmazonSesLimitRequest"}},"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":{"allOf":[{"$ref":"#/components/schemas/SharedAmazonSesLimitRequest"},{"type":"object"}]},"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"},"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"}},"required":["id","provider_id","provider_name","message_id","from_email","sent_from_email","to_email","subject","status","status_reason","attempts","sent_at","size_bytes","created_at"],"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},"DeliveryLogItemResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/DeliveryLogItem"}},"required":["data"]}],"unevaluatedProperties":false},"Balance":{"type":"object","properties":{"balance":{"type":"string","description":"Current balance (purchased - consumed)","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.sendmux.ai"}},"required":["priority","target"],"additionalProperties":false},"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 covering both SES and Sendmux includes"},"MailboxDomainDnsRecords":{"type":"object","properties":{"mx":{"type":"array","items":{"$ref":"#/components/schemas/MailboxDomainMxRecord"},"description":"MX records the customer must place. All point at Sendmux's inbound mail servers."},"spf":{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"},"dmarc":{"allOf":[{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"},{"description":"DMARC enforcement record (quarantine, no reporting)"}]},"dkim":{"type":"array","items":{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"},"description":"Three SES DKIM CNAME records"},"verification":{"allOf":[{"$ref":"#/components/schemas/MailboxDomainNameValueRecord"},{"description":"Ownership-proof TXT record (Sendmux-specific)"}]}},"required":["mx","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"},"verification_status":{"type":"string","enum":["pending","verified","failed"],"description":"Current verification state"},"ses_dkim_status":{"type":["string","null"],"description":"SES DKIM 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","verification_status","ses_dkim_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 with priority 10 pointing at mail.sendmux.ai"},"verification_txt":{"type":"boolean","description":"Ownership TXT record present with correct value"},"spf":{"type":"boolean","description":"SPF TXT record matches expected value"},"dmarc":{"type":"boolean","description":"DMARC TXT record matches expected value"}},"required":["mx","verification_txt","spf","dmarc"],"additionalProperties":false},"MailboxDomainVerifyResult":{"type":"object","properties":{"status":{"type":"string","enum":["verified","pending"],"description":"Post-check verification status"},"ses_dkim_status":{"type":"string","description":"Latest SES DKIM status from AWS"},"checks":{"$ref":"#/components/schemas/MailboxDomainVerifyChecks"}},"required":["status","ses_dkim_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},"MailboxCredential":{"type":["object","null"],"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.sendmux.ai"},"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,"description":"Initial credential for the mailbox. `null` if credential generation failed — call POST /mailboxes/{id}/keys to retry."},"MailboxCreateResult":{"type":"object","properties":{"mailbox":{"$ref":"#/components/schemas/Mailbox"},"credential":{"$ref":"#/components/schemas/MailboxCredential"},"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},"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"]},"provider_public_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"group_public_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128}}},"required":["type"],"additionalProperties":false}},"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":{"allOf":[{"$ref":"#/components/schemas/MailboxCredential"},{"type":"object"}]}},"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},"MailboxMe":{"allOf":[{"$ref":"#/components/schemas/Mailbox"},{"type":"object","properties":{"quota_used_bytes":{"type":"integer","description":"Live storage usage in bytes. Omitted when usage is temporarily unavailable."}},"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},"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":{"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":["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},"MailboxIdentityCursorListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxIdentity"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxSubmissionEnvelopeAddress":{"type":["object","null"],"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":{"$ref":"#/components/schemas/MailboxSubmissionEnvelopeAddress"},"rcpt_to":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/MailboxSubmissionEnvelopeAddress"},{"type":"object"}]}}},"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/ResponseMeta"},"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"}}},"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/ResponseMeta"},"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},"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":{"allOf":[{"$ref":"#/components/schemas/MailboxAddress"},{"type":["object","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"},"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/ResponseMeta"},"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","null"],"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},"MailboxAttachment":{"type":"object","properties":{"id":{"type":"string","description":"Attachment ID"},"filename":{"type":["string","null"]},"content_type":{"type":"string","example":"application/pdf"},"size_bytes":{"type":["integer","null"]},"disposition":{"type":["string","null"]},"content_id":{"type":["string","null"]},"download_url":{"type":"string"}},"required":["id","filename","content_type","size_bytes","disposition","content_id"],"additionalProperties":false},"MailboxMessageContent":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Message ID"},"thread_id":{"type":["string","null"]},"subject":{"type":["string","null"]},"participants":{"type":"object","properties":{"from":{"allOf":[{"$ref":"#/components/schemas/MailboxAddress"},{"type":["object","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."},"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","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":{"$ref":"#/components/schemas/MailboxRawBody"},"content":{"$ref":"#/components/schemas/MailboxMessageContent"}},"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},"body_mode":{"type":"string","enum":["none","raw","clean_json"]},"part":{"type":"string","enum":["auto","text","html","both"]},"max_body_chars":{"type":"integer","minimum":1,"maximum":1000000},"strip_signature":{"type":"boolean"},"strip_quotes":{"type":"boolean"},"include_links":{"type":"boolean"},"include_html":{"type":"boolean"},"include_headers":{"type":"string","enum":["none","selected","full"]},"include_attachments":{"type":"string","enum":["none","metadata"]}},"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},"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}},"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},"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},"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":{"$ref":"#/components/schemas/MailboxAddress"},"to":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAddress"},"minItems":1},"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"}},"subject":{"type":"string"},"text_body":{"type":"string"},"html_body":{"type":"string"},"custom_headers":{"type":"object","additionalProperties":{"type":"string"}},"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}]}}},"required":["to","subject"],"additionalProperties":false},"MailboxMessage":{"allOf":[{"$ref":"#/components/schemas/MailboxMessageSummary"},{"type":"object","properties":{"text_body":{"type":["string","null"]},"html_body":{"type":["string","null"]},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAttachment"}}},"required":["text_body","html_body","attachments"],"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":{"allOf":[{"$ref":"#/components/schemas/MailboxRawBody"},{"type":"object"}]}},"required":["data"]}],"unevaluatedProperties":false},"MailboxMessageContentResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"allOf":[{"$ref":"#/components/schemas/MailboxMessageContent"},{"type":"object"}]}},"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":{"allOf":[{"$ref":"#/components/schemas/MailboxMessageSummary"},{"type":["object","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/ResponseMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxThreadSummary"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"required":["data","pagination"]}],"unevaluatedProperties":false},"MailboxThread":{"allOf":[{"$ref":"#/components/schemas/MailboxThreadSummary"},{"type":"object","properties":{"message_ids":{"type":"array","items":{"type":"string"}}},"required":["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},"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":{"allOf":[{"$ref":"#/components/schemas/MailboxMessageContent"},{"type":"object"}]}},"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":{"allOf":[{"$ref":"#/components/schemas/MailboxMessageSummary"},{"type":["object","null"],"properties":{"rfc5322_message_id":{"type":["string","null"]},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAttachment"}},"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":["rfc5322_message_id","attachments","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},"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.","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","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":{"allOf":[{"$ref":"#/components/schemas/WebhookSubscription"},{"type":"object","properties":{"secret":{"type":"string","description":"Signing secret used to verify the HMAC-SHA256 signature on every event POST. This is the ONLY response containing the raw secret — store it securely; it cannot be retrieved later. Use POST /webhooks/{id}/rotate-secret to issue a new one.","example":"whsec_a9f3c2…"}},"required":["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","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","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","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":"Sendmux message correlation ID for outbound sending feedback when available.","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},"WebhookEventPayload":{"type":"object","properties":{"id":{"type":"string","description":"Stable per-event identifier. Also sent in the X-Sendmux-Event-Id header.","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-Sendmux-Event-Type header.","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,"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,"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","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-Sendmux-Event-Id header of the test delivery.","example":"evt_clxxxxxxxxxxxxxxxxxxxxxxxxx"}},"required":["event_id"],"additionalProperties":false}},"parameters":{}},"paths":{"/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":[]}],"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":[]}],"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":[]}],"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"}}}}}}},"/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":[]}],"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. The shared Amazon SES account cannot be edited here; use activate/deactivate and the limit-request endpoint for the allowed shared-account actions.","tags":["Sending accounts"],"security":[{"bearerAuth":[]}],"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"}}}},"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":[]}],"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":[]}],"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":[]}],"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":[]}],"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":[]}],"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":[]}],"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":[]}],"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"}}}},"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":[]}],"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":[]}],"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"}}}},"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":[]}],"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":[]}],"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"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"ISO 8601 start date"},"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","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":[]}],"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 team balance and auto top-up configuration.","tags":["Billing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Current 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":[]}],"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":[]}],"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":[]}],"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 sending domain and returns the DNS records the customer must place before verification can succeed. Provisioning touches both our mail 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":[]}],"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"}},"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"}}}},"503":{"description":"SES tenant not yet provisioned for this team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/domains/{public_id}":{"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":[]}],"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 Sendmux. Blocked if any active mailbox still uses the domain — delete those mailboxes first.","tags":["Domains"],"security":[{"bearerAuth":[]}],"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"}}}}}}},"/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":[]}],"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":"Runs an immediate DNS-over-HTTPS check of the domain's MX, SPF, DMARC and ownership TXT records, then asks SES for the latest DKIM status. If every check passes the domain is marked verified. Domains automatically re-verify every 6 hours — this endpoint is only needed to trigger a check on demand.","tags":["Domains"],"security":[{"bearerAuth":[]}],"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"}}}}}}},"/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":[]}],"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 soft-deleted mailboxes (status `deleted`) in the response. Default `false`. Soft-deleted mailboxes are retained for tenant-isolation references in delivery logs and API keys."},"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":[]}],"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},"display_name":{"type":"string","minLength":1,"maxLength":254},"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"]},"provider_public_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"group_public_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128}}},"required":["type"],"additionalProperties":false}},"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"}}}},"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/{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":[]}],"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":[]}],"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"}}}},"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 Sendmux. All associated API keys are revoked.","tags":["Mailboxes"],"security":[{"bearerAuth":[]}],"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"}}}}}}},"/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":[]}],"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":"Root API key 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":[]}],"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":"Root API key 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":[]}],"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}},"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":"API key limit reached (`limit_exceeded`) or idempotency key conflict (`idempotency_conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Mailbox is not active","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":[]}],"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/me":{"get":{"operationId":"mailboxGetMe","summary":"Self-introspect the calling mailbox","description":"Returns the mailbox the bearer token is scoped to, including live storage usage. Intended for SDK auto-discovery — call once on startup to resolve the mailbox ID. Requires a mailbox-scoped API key; root keys receive 403.\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":[]}],"parameters":[{"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":"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"}}}}}}},"/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":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"}],"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 key 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":[]}],"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 key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Mailbox service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"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":[]}],"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 key required","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"}}}}}}},"/mailbox/identities":{"get":{"operationId":"mailboxListIdentities","summary":"List mailbox sender identities","description":"Returns sender identities available to the authenticated mailbox.","tags":["Mailbox API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"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 key 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":[]}],"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"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"submission_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"}],"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":[]}],"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"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"}],"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 a mailbox API key.","tags":["Mailbox API"],"security":[{"bearerAuth":[]}],"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":"folder_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"thread_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cc","in":"query"},{"schema":{"type":"string"},"required":false,"name":"bcc","in":"query"},{"schema":{"type":"string"},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string"},"required":false,"name":"body","in":"query"},{"schema":{"type":"string"},"required":false,"name":"header_name","in":"query"},{"schema":{"type":"string"},"required":false,"name":"header_value","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"min_size_bytes","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"max_size_bytes","in":"query"},{"schema":{"type":"string"},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"string"},"required":false,"name":"not_keyword","in":"query"},{"schema":{"type":"string"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean"},"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"}],"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 key 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":[]}],"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"},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cc","in":"query"},{"schema":{"type":"string"},"required":false,"name":"bcc","in":"query"},{"schema":{"type":"string"},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string"},"required":false,"name":"body","in":"query"},{"schema":{"type":"string"},"required":false,"name":"header_name","in":"query"},{"schema":{"type":"string"},"required":false,"name":"header_value","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"min_size_bytes","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"max_size_bytes","in":"query"},{"schema":{"type":"string"},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"string"},"required":false,"name":"not_keyword","in":"query"},{"schema":{"type":"string"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean"},"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"}],"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":[]}],"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"}}}}}}},"/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":[]}],"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"}}}}}}},"/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":[]}],"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"}}}}}}},"/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":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"thread_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cc","in":"query"},{"schema":{"type":"string"},"required":false,"name":"bcc","in":"query"},{"schema":{"type":"string"},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string"},"required":false,"name":"body","in":"query"},{"schema":{"type":"string"},"required":false,"name":"header_name","in":"query"},{"schema":{"type":"string"},"required":false,"name":"header_value","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"min_size_bytes","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"max_size_bytes","in":"query"},{"schema":{"type":"string"},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"string"},"required":false,"name":"not_keyword","in":"query"},{"schema":{"type":"string"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"is_unread","in":"query"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cc","in":"query"},{"schema":{"type":"string"},"required":false,"name":"bcc","in":"query"},{"schema":{"type":"string"},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string"},"required":false,"name":"body","in":"query"},{"schema":{"type":"string"},"required":false,"name":"header_name","in":"query"},{"schema":{"type":"string"},"required":false,"name":"header_value","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"min_size_bytes","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"max_size_bytes","in":"query"},{"schema":{"type":"string"},"required":false,"name":"keyword","in":"query"},{"schema":{"type":"string"},"required":false,"name":"not_keyword","in":"query"},{"schema":{"type":"string"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"is_unread","in":"query"},{"schema":{"type":"string"},"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},"required":false,"name":"limit","in":"query"}],"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":[]}],"parameters":[{"schema":{"type":"string","description":"Filename to use when sending the uploaded attachment."},"required":true,"name":"filename","in":"query"}],"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/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`.","tags":["Mailbox API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255},"required":false,"name":"Idempotency-Key","in":"header"}],"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"}}}},"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.","tags":["Mailbox API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"}],"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 with state-safe conflict handling. Send `If-Match` with a prior ETag to reject stale edits.","tags":["Mailbox API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-Match","in":"header"}],"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"}}}}}},"delete":{"operationId":"mailboxDeleteMessage","summary":"Delete a mailbox message","description":"Moves a message to Trash by default with state-safe conflict handling. Set `permanent=true` to permanently delete it. Send `If-Match` with a prior ETag to reject stale deletes.","tags":["Mailbox API"],"security":[{"bearerAuth":[]}],"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"}],"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}/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":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string","enum":["text","html","both"]},"required":false,"name":"part","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000000},"required":false,"name":"max_body_chars","in":"query"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string","enum":["auto","text","html"]},"required":false,"name":"part","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000000},"required":false,"name":"max_body_chars","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"strip_signature","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"strip_quotes","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"include_links","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"include_html","in":"query"},{"schema":{"type":"string","enum":["none","selected","full"]},"required":false,"name":"include_headers","in":"query"},{"schema":{"type":"string","enum":["none","metadata"]},"required":false,"name":"include_attachments","in":"query"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"}],"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":[]}],"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":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"participant","in":"query"},{"schema":{"type":"string"},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"before","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"has_attachment","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"is_unread","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"sort_direction","in":"query"}],"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 key 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":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"},{"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"}],"responses":{"200":{"description":"Thread messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxMessageSummaryCursorListResponse"}}}},"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":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"},{"schema":{"type":"string","enum":["auto","text","html"]},"required":false,"name":"part","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000000},"required":false,"name":"max_body_chars","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"strip_signature","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"strip_quotes","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"include_links","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"include_html","in":"query"},{"schema":{"type":"string","enum":["none","selected","full"]},"required":false,"name":"include_headers","in":"query"},{"schema":{"type":"string","enum":["none","metadata"]},"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"}],"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 in the authenticated mailbox. Supports standard byte ranges.","tags":["Mailbox API"],"security":[{"bearerAuth":[]}],"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"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"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":[]}],"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"}}}},"422":{"description":"Folder validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/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":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"}],"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":[]}],"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"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"folder_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-None-Match","in":"header"}],"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 with state-safe conflict handling. Send `If-Match` with a prior ETag to reject stale edits.","tags":["Mailbox API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"folder_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-Match","in":"header"}],"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"}}}}}},"delete":{"operationId":"mailboxDeleteFolder","summary":"Delete a mailbox folder","description":"Deletes an empty custom folder with state-safe conflict handling. 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":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"folder_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"If-Match","in":"header"}],"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":[]}],"parameters":[{"schema":{"type":"string"},"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"},"required":false,"name":"messages_since_state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"folders_since_state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"threads_since_state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"submissions_since_state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"identities_since_state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"quotas_since_state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"}],"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":[]}],"parameters":[{"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"}}}}}}},"/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":[]}],"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":[]}],"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"}}}},"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. 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":[]}],"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"}}}},"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 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":[]}],"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.","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":[]}],"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"},"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","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":[]}],"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":[]}],"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":[]}],"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"}}}},"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":[]}],"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":[]}],"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"}}}},"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":[]}],"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":[]}],"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","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":[]}],"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":[]}],"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-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":[]}],"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":{}}