{
  "components": {
    "parameters": {},
    "schemas": {
      "ApiError": {
        "additionalProperties": false,
        "properties": {
          "error": {
            "additionalProperties": false,
            "properties": {
              "code": {
                "description": "Machine-readable error code",
                "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"
                ],
                "example": "invalid_parameter",
                "type": "string"
              },
              "doc_url": {
                "description": "Link to relevant documentation",
                "type": "string"
              },
              "errors": {
                "description": "Accumulated per-field issues for validation errors. Only present on 400/422 responses.",
                "items": {
                  "$ref": "#/components/schemas/ApiErrorDetail"
                },
                "type": "array"
              },
              "message": {
                "description": "Human-readable error description",
                "type": "string"
              },
              "param": {
                "description": "The parameter that caused the error",
                "type": "string"
              },
              "retryable": {
                "description": "Whether the caller may safely retry this request. 4xx are typically false (except 429); 5xx are typically true.",
                "example": false,
                "type": "boolean"
              }
            },
            "required": [
              "code",
              "message",
              "retryable"
            ],
            "type": "object"
          },
          "meta": {
            "additionalProperties": false,
            "properties": {
              "request_id": {
                "example": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx",
                "type": "string"
              }
            },
            "required": [
              "request_id"
            ],
            "type": "object"
          },
          "ok": {
            "enum": [
              false
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "error",
          "meta"
        ],
        "type": "object"
      },
      "ApiErrorDetail": {
        "additionalProperties": false,
        "properties": {
          "code": {
            "description": "Machine-readable issue code from the validator (e.g. zod issue code).",
            "example": "invalid_string",
            "type": "string"
          },
          "field": {
            "description": "Dot-path of the offending request field.",
            "example": "recipient.email",
            "type": "string"
          },
          "message": {
            "description": "Human-readable issue description.",
            "type": "string"
          }
        },
        "required": [
          "field",
          "code",
          "message"
        ],
        "type": "object"
      },
      "Balance": {
        "additionalProperties": false,
        "properties": {
          "auto_topup": {
            "additionalProperties": false,
            "properties": {
              "amount": {
                "example": "50.000000",
                "type": [
                  "string",
                  "null"
                ]
              },
              "enabled": {
                "type": "boolean"
              },
              "monthly_limit": {
                "example": "200.000000",
                "type": [
                  "string",
                  "null"
                ]
              },
              "monthly_used": {
                "example": "50.000000",
                "type": "string"
              },
              "threshold": {
                "example": "10.000000",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "enabled",
              "threshold",
              "amount",
              "monthly_limit",
              "monthly_used"
            ],
            "type": "object"
          },
          "balance": {
            "description": "Current balance (purchased - consumed)",
            "example": "45.230000",
            "type": "string"
          },
          "balance_consumed": {
            "example": "54.770000",
            "type": "string"
          },
          "balance_purchased": {
            "example": "100.000000",
            "type": "string"
          },
          "currency": {
            "enum": [
              "USD"
            ],
            "type": "string"
          }
        },
        "required": [
          "balance",
          "balance_purchased",
          "balance_consumed",
          "currency",
          "auto_topup"
        ],
        "type": "object"
      },
      "BalanceResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Balance"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "BatchDeleteMailboxMessagesBody": {
        "additionalProperties": false,
        "properties": {
          "ids": {
            "description": "Message IDs to delete, maximum 100.",
            "items": {
              "type": "string"
            },
            "maxItems": 100,
            "minItems": 1,
            "type": "array"
          },
          "if_in_state": {
            "description": "Optional message state token for stale-write protection.",
            "type": "string"
          },
          "permanent": {
            "description": "When true, permanently deletes instead of moving to Trash.",
            "type": "boolean"
          }
        },
        "required": [
          "ids"
        ],
        "type": "object"
      },
      "BatchUpdateMailboxMessagesBody": {
        "additionalProperties": false,
        "properties": {
          "flagged": {
            "description": "Set or clear the flagged marker.",
            "type": "boolean"
          },
          "ids": {
            "description": "Message IDs to update, maximum 100.",
            "items": {
              "type": "string"
            },
            "maxItems": 100,
            "minItems": 1,
            "type": "array"
          },
          "if_in_state": {
            "description": "Optional message state token for stale-write protection.",
            "type": "string"
          },
          "keywords": {
            "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
            },
            "type": "object"
          },
          "seen": {
            "description": "Set or clear the seen flag.",
            "type": "boolean"
          }
        },
        "required": [
          "ids"
        ],
        "type": "object"
      },
      "CreateMailboxFolderBody": {
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "sort_order": {
            "type": "integer"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "CursorPagination": {
        "additionalProperties": false,
        "properties": {
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "has_more"
        ],
        "type": "object"
      },
      "DeliveryLogItem": {
        "additionalProperties": false,
        "properties": {
          "attempts": {
            "type": "number"
          },
          "created_at": {
            "description": "ISO 8601 creation timestamp",
            "type": "string"
          },
          "from_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Log public ID",
            "example": "dlog_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "message_id": {
            "description": "Email Message-ID header",
            "type": [
              "string",
              "null"
            ]
          },
          "provider_id": {
            "description": "Provider public ID",
            "type": [
              "string",
              "null"
            ]
          },
          "provider_name": {
            "description": "Provider display name",
            "type": [
              "string",
              "null"
            ]
          },
          "sent_at": {
            "description": "ISO 8601 timestamp when email was sent",
            "type": [
              "string",
              "null"
            ]
          },
          "sent_from_email": {
            "description": "The actual from address used for delivery after transformation. NULL if no transformation occurred or for older log entries.",
            "type": [
              "string",
              "null"
            ]
          },
          "size_bytes": {
            "type": [
              "number",
              "null"
            ]
          },
          "status": {
            "enum": [
              "pending",
              "sent",
              "failed",
              "rejected"
            ],
            "type": "string"
          },
          "status_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "to_email": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "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"
        ],
        "type": "object"
      },
      "DeliveryLogItemCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/DeliveryLogItem"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "DeliveryLogItemResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/DeliveryLogItem"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "DomainDeletedResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "additionalProperties": false,
                "properties": {
                  "deleted": {
                    "enum": [
                      true
                    ],
                    "type": "boolean"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "deleted",
                  "id"
                ],
                "type": "object"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "DomainItemCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/MailboxDomain"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "DomainItemResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxDomain"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "DomainVerifyResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxDomainVerifyResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "EmailMetrics": {
        "additionalProperties": false,
        "properties": {
          "comparison": {
            "additionalProperties": false,
            "properties": {
              "change_pct": {
                "additionalProperties": false,
                "properties": {
                  "failed": {
                    "example": 10.53,
                    "type": "number"
                  },
                  "pending": {
                    "example": 0,
                    "type": "number"
                  },
                  "rejected": {
                    "example": 33.33,
                    "type": "number"
                  },
                  "sent": {
                    "example": 7.9,
                    "type": "number"
                  },
                  "total": {
                    "example": 8.01,
                    "type": "number"
                  }
                },
                "required": [
                  "total",
                  "sent",
                  "failed",
                  "rejected",
                  "pending"
                ],
                "type": "object"
              },
              "failed": {
                "example": 210,
                "type": "number"
              },
              "pending": {
                "example": 50,
                "type": "number"
              },
              "rejected": {
                "example": 80,
                "type": "number"
              },
              "sent": {
                "example": 14890,
                "type": "number"
              },
              "total": {
                "example": 15230,
                "type": "number"
              }
            },
            "required": [
              "total",
              "sent",
              "failed",
              "rejected",
              "pending",
              "change_pct"
            ],
            "type": "object"
          },
          "summary": {
            "additionalProperties": false,
            "properties": {
              "failed": {
                "example": 210,
                "type": "number"
              },
              "pending": {
                "example": 50,
                "type": "number"
              },
              "rejected": {
                "example": 80,
                "type": "number"
              },
              "sent": {
                "example": 14890,
                "type": "number"
              },
              "total": {
                "example": 15230,
                "type": "number"
              }
            },
            "required": [
              "total",
              "sent",
              "failed",
              "rejected",
              "pending"
            ],
            "type": "object"
          },
          "timeseries": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "failed": {
                  "type": "number"
                },
                "pending": {
                  "type": "number"
                },
                "rejected": {
                  "type": "number"
                },
                "sent": {
                  "type": "number"
                },
                "timestamp": {
                  "example": "2026-03-19T00:00:00Z",
                  "type": "string"
                },
                "total": {
                  "type": "number"
                }
              },
              "required": [
                "timestamp",
                "total",
                "sent",
                "failed",
                "rejected",
                "pending"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "summary",
          "comparison",
          "timeseries"
        ],
        "type": "object"
      },
      "EmailMetricsResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/EmailMetrics"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "FilterRule": {
        "additionalProperties": false,
        "properties": {
          "note": {
            "description": "Free-form caption for the rule (≤255 chars). UI-only metadata — never consulted at match time. `null` when absent.",
            "example": "billing webhooks",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "pattern": {
            "description": "Email address or bare domain name. Validated against RFC 5321/1035 regexes. The `*@domain` wildcard spelling is accepted and normalised to the bare domain (matching is by exact address or sender domain).",
            "example": "partner.com",
            "type": "string"
          },
          "type": {
            "description": "Rule type",
            "enum": [
              "allow",
              "deny"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "pattern"
        ],
        "type": "object"
      },
      "FilterState": {
        "additionalProperties": false,
        "properties": {
          "mode": {
            "description": "Active filtering mode. `off` disables filtering (all senders accepted). `allowlist` only accepts senders matching a rule. `denylist` blocks senders matching a rule.",
            "enum": [
              "off",
              "allowlist",
              "denylist"
            ],
            "type": "string"
          },
          "rules": {
            "description": "Current rules, sorted by pattern ascending",
            "items": {
              "$ref": "#/components/schemas/FilterRule"
            },
            "type": "array"
          }
        },
        "required": [
          "mode",
          "rules"
        ],
        "type": "object"
      },
      "FilterStateResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/FilterState"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "GrantedMailbox": {
        "additionalProperties": false,
        "properties": {
          "email": {
            "description": "Mailbox email address",
            "example": "agent@acme.com",
            "type": "string"
          },
          "id": {
            "description": "Mailbox public ID",
            "example": "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          }
        },
        "required": [
          "id",
          "email"
        ],
        "type": "object"
      },
      "GrantedMailboxListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/GrantedMailbox"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "IncomingLogItem": {
        "additionalProperties": false,
        "properties": {
          "amount": {
            "description": "Billable amount for this message in USD",
            "type": "string"
          },
          "billing_bucket_start": {
            "description": "ISO 8601 usage bucket start",
            "type": "string"
          },
          "event_type": {
            "enum": [
              "message.received",
              "message.received.spam"
            ],
            "type": "string"
          },
          "from_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Incoming log public ID",
            "example": "ilog_9ed2f2fdbacf38ef05c6a8b9",
            "type": "string"
          },
          "is_spam": {
            "type": "boolean"
          },
          "mailbox_email": {
            "description": "Mailbox email address",
            "type": [
              "string",
              "null"
            ]
          },
          "mailbox_id": {
            "description": "Mailbox public ID",
            "type": [
              "string",
              "null"
            ]
          },
          "message_id": {
            "description": "Message identifier when available",
            "type": [
              "string",
              "null"
            ]
          },
          "message_id_kind": {
            "description": "Identifier source when available",
            "type": [
              "string",
              "null"
            ]
          },
          "received_at": {
            "description": "ISO 8601 received timestamp",
            "type": "string"
          },
          "size_bytes": {
            "type": [
              "number",
              "null"
            ]
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "to_emails": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "unit_amount": {
            "description": "Per-message unit amount in USD",
            "type": "string"
          }
        },
        "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"
        ],
        "type": "object"
      },
      "IncomingLogItemCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/IncomingLogItem"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "IncomingLogItemResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/IncomingLogItem"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "Mailbox": {
        "additionalProperties": false,
        "properties": {
          "created_at": {
            "description": "ISO 8601 creation timestamp",
            "type": "string"
          },
          "display_name": {
            "description": "Optional display name shown in outbound From headers",
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "description": "Mailbox email address (lowercase)",
            "example": "agent@acme.com",
            "type": "string"
          },
          "id": {
            "description": "Public ID",
            "example": "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "quota_bytes": {
            "description": "Storage quota in bytes. Current writable tiers are 1 GB, 5 GB, and 50 GB.",
            "type": [
              "integer",
              "null"
            ]
          },
          "send_scope": {
            "$ref": "#/components/schemas/MailboxSendScope"
          },
          "status": {
            "description": "active | suspended | deleted",
            "example": "active",
            "type": "string"
          }
        },
        "required": [
          "id",
          "email",
          "display_name",
          "quota_bytes",
          "send_scope",
          "status",
          "created_at"
        ],
        "type": "object"
      },
      "MailboxAddress": {
        "additionalProperties": false,
        "properties": {
          "email": {
            "example": "agent@example.com",
            "format": "email",
            "type": "string"
          },
          "name": {
            "example": "Support",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "email",
          "name"
        ],
        "type": "object"
      },
      "MailboxAppPasswordResult": {
        "additionalProperties": false,
        "properties": {
          "credential": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MailboxCredential"
              },
              {
                "type": "object"
              }
            ]
          }
        },
        "required": [
          "credential"
        ],
        "type": "object"
      },
      "MailboxAppPasswordResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxAppPasswordResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxAttachment": {
        "additionalProperties": false,
        "properties": {
          "content_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "content_type": {
            "example": "application/pdf",
            "type": "string"
          },
          "disposition": {
            "type": [
              "string",
              "null"
            ]
          },
          "download_url": {
            "type": "string"
          },
          "filename": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Attachment ID",
            "type": "string"
          },
          "size_bytes": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "filename",
          "content_type",
          "size_bytes",
          "disposition",
          "content_id"
        ],
        "type": "object"
      },
      "MailboxAttachmentUploadResult": {
        "additionalProperties": false,
        "properties": {
          "blob_id": {
            "description": "Uploaded attachment blob ID for a later send request.",
            "type": "string"
          },
          "content_type": {
            "example": "application/pdf",
            "type": "string"
          },
          "filename": {
            "example": "invoice.pdf",
            "type": "string"
          },
          "size_bytes": {
            "example": 12345,
            "type": "integer"
          }
        },
        "required": [
          "blob_id",
          "filename",
          "content_type",
          "size_bytes"
        ],
        "type": "object"
      },
      "MailboxAttachmentUploadResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxAttachmentUploadResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxAvailabilityReason": {
        "enum": [
          "available",
          "invalid_email",
          "domain_not_available",
          "taken",
          "reserved",
          "cleanup_pending"
        ],
        "type": "string"
      },
      "MailboxAvailabilityResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxAvailabilityResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxAvailabilityResult": {
        "additionalProperties": false,
        "properties": {
          "available": {
            "description": "Whether this address can be reserved for mailbox creation.",
            "type": "boolean"
          },
          "email": {
            "description": "Normalised mailbox email address checked.",
            "example": "agent@myagent.mx",
            "type": "string"
          },
          "reason": {
            "$ref": "#/components/schemas/MailboxAvailabilityReason"
          }
        },
        "required": [
          "email",
          "available",
          "reason"
        ],
        "type": "object"
      },
      "MailboxBatchDeleteMessagesResult": {
        "additionalProperties": false,
        "properties": {
          "deleted": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "failed": {
            "items": {
              "$ref": "#/components/schemas/MailboxBatchMessageFailure"
            },
            "type": "array"
          },
          "not_found": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "states": {
            "$ref": "#/components/schemas/MailboxBatchMessageStates"
          }
        },
        "required": [
          "deleted",
          "not_found",
          "failed",
          "states"
        ],
        "type": "object"
      },
      "MailboxBatchDeleteMessagesResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxBatchDeleteMessagesResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxBatchGetBody": {
        "additionalProperties": false,
        "properties": {
          "body_mode": {
            "description": "Body shape to include for each message.",
            "enum": [
              "none",
              "raw",
              "clean_json"
            ],
            "type": "string"
          },
          "ids": {
            "description": "Message IDs to fetch, maximum 100.",
            "items": {
              "type": "string"
            },
            "maxItems": 100,
            "minItems": 1,
            "type": "array"
          },
          "include_attachments": {
            "description": "Attachment detail to include. Contents are not returned.",
            "enum": [
              "none",
              "metadata"
            ],
            "type": "string"
          },
          "include_headers": {
            "description": "Header detail to include in each message.",
            "enum": [
              "none",
              "selected",
              "full"
            ],
            "type": "string"
          },
          "include_html": {
            "description": "When true, include HTML content when available.",
            "type": "boolean"
          },
          "include_links": {
            "description": "When true, include links extracted from the body.",
            "type": "boolean"
          },
          "max_body_chars": {
            "description": "Maximum body characters per message before truncation.",
            "maximum": 1000000,
            "minimum": 1,
            "type": "integer"
          },
          "part": {
            "description": "Body part to return when body_mode is not `none`.",
            "enum": [
              "auto",
              "text",
              "html",
              "both"
            ],
            "type": "string"
          },
          "strip_quotes": {
            "description": "When true, remove quoted reply text.",
            "type": "boolean"
          },
          "strip_signature": {
            "description": "When true, remove detected email signatures.",
            "type": "boolean"
          }
        },
        "required": [
          "ids"
        ],
        "type": "object"
      },
      "MailboxBatchGetItem": {
        "additionalProperties": false,
        "properties": {
          "content": {
            "$ref": "#/components/schemas/MailboxMessageContent"
          },
          "message": {
            "$ref": "#/components/schemas/MailboxMessageSummary"
          },
          "raw_body": {
            "$ref": "#/components/schemas/MailboxRawBody"
          }
        },
        "required": [
          "message",
          "raw_body",
          "content"
        ],
        "type": "object"
      },
      "MailboxBatchGetResult": {
        "additionalProperties": false,
        "properties": {
          "messages": {
            "items": {
              "$ref": "#/components/schemas/MailboxBatchGetItem"
            },
            "type": "array"
          },
          "not_found": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "states": {
            "additionalProperties": false,
            "properties": {
              "email_state": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "email_state"
            ],
            "type": "object"
          }
        },
        "required": [
          "messages",
          "not_found",
          "states"
        ],
        "type": "object"
      },
      "MailboxBatchGetResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxBatchGetResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxBatchMessageFailure": {
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "code",
          "message"
        ],
        "type": "object"
      },
      "MailboxBatchMessageStates": {
        "additionalProperties": false,
        "properties": {
          "new_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "old_state": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "old_state",
          "new_state"
        ],
        "type": "object"
      },
      "MailboxBatchUpdateMessagesResult": {
        "additionalProperties": false,
        "properties": {
          "failed": {
            "items": {
              "$ref": "#/components/schemas/MailboxBatchMessageFailure"
            },
            "type": "array"
          },
          "not_found": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "states": {
            "$ref": "#/components/schemas/MailboxBatchMessageStates"
          },
          "updated": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "updated",
          "not_found",
          "failed",
          "states"
        ],
        "type": "object"
      },
      "MailboxBatchUpdateMessagesResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxBatchUpdateMessagesResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxChanges": {
        "additionalProperties": false,
        "properties": {
          "created": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "destroyed": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "new_state": {
            "type": "string"
          },
          "old_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "sync_required": {
            "description": "When true, refetch this resource list instead of applying the incremental arrays.",
            "type": "boolean"
          },
          "updated": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "updated_properties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "old_state",
          "new_state",
          "has_more",
          "created",
          "updated",
          "destroyed"
        ],
        "type": "object"
      },
      "MailboxChangesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxChanges"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxContentHeaders": {
        "additionalProperties": false,
        "properties": {
          "full": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "name": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "value"
              ],
              "type": "object"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "mode": {
            "enum": [
              "none",
              "selected",
              "full"
            ],
            "type": "string"
          },
          "selected": {
            "properties": {
              "in_reply_to": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "message_id": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "references": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "reply_to": {
                "items": {
                  "$ref": "#/components/schemas/MailboxAddress"
                },
                "type": "array"
              }
            },
            "required": [
              "message_id",
              "in_reply_to",
              "references",
              "reply_to"
            ],
            "type": [
              "object",
              "null"
            ]
          }
        },
        "required": [
          "mode",
          "selected",
          "full"
        ],
        "type": "object"
      },
      "MailboxCreateResult": {
        "additionalProperties": false,
        "properties": {
          "credential": {
            "$ref": "#/components/schemas/MailboxCredential"
          },
          "mailbox": {
            "$ref": "#/components/schemas/Mailbox"
          },
          "warning": {
            "description": "Optional warning string when the mailbox was created without an initial credential",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "mailbox",
          "credential",
          "warning"
        ],
        "type": "object"
      },
      "MailboxCreateResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxCreateResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxCredential": {
        "additionalProperties": false,
        "description": "Initial credential for the mailbox. `null` if credential generation failed — call POST /mailboxes/{id}/keys to retry.",
        "properties": {
          "imap_port": {
            "description": "IMAP retrieval port",
            "example": 993,
            "type": "integer"
          },
          "key_prefix": {
            "type": "string"
          },
          "key_suffix": {
            "type": "string"
          },
          "public_id": {
            "description": "Credential public ID",
            "example": "smx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "secret": {
            "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.",
            "type": "string"
          },
          "server": {
            "description": "Mailbox server name",
            "example": "mail.sendmux.ai",
            "type": "string"
          },
          "smtp_port": {
            "description": "SMTP submission port",
            "example": 587,
            "type": "integer"
          },
          "username": {
            "description": "Mailbox email address used as the login",
            "type": "string"
          }
        },
        "required": [
          "public_id",
          "secret",
          "key_prefix",
          "key_suffix",
          "server",
          "imap_port",
          "smtp_port",
          "username"
        ],
        "type": [
          "object",
          "null"
        ]
      },
      "MailboxDeletedResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "additionalProperties": false,
                "properties": {
                  "deleted": {
                    "enum": [
                      true
                    ],
                    "type": "boolean"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "deleted",
                  "id"
                ],
                "type": "object"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxDomain": {
        "additionalProperties": false,
        "properties": {
          "created_at": {
            "description": "ISO 8601 creation timestamp",
            "type": "string"
          },
          "dns_records": {
            "$ref": "#/components/schemas/MailboxDomainDnsRecords"
          },
          "domain": {
            "description": "Fully qualified domain name",
            "example": "mail.acme.com",
            "type": "string"
          },
          "id": {
            "description": "Public ID",
            "example": "mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "mailbox_count": {
            "description": "Active mailboxes currently using this domain",
            "example": 14,
            "minimum": 0,
            "type": "integer"
          },
          "mode": {
            "description": "`send_only` verifies outbound DNS only. `send_receive` also verifies MX records and can host mailboxes.",
            "enum": [
              "send_only",
              "send_receive"
            ],
            "example": "send_receive",
            "type": "string"
          },
          "ses_dkim_status": {
            "description": "Amazon SES DKIM status (pending/success/failed/temporary_failure/not_started)",
            "type": [
              "string",
              "null"
            ]
          },
          "verification_status": {
            "description": "Current verification state",
            "enum": [
              "pending",
              "verified",
              "failed"
            ],
            "type": "string"
          },
          "verified_at": {
            "description": "ISO 8601 timestamp of last successful verification",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "domain",
          "mode",
          "verification_status",
          "ses_dkim_status",
          "verified_at",
          "created_at",
          "mailbox_count",
          "dns_records"
        ],
        "type": "object"
      },
      "MailboxDomainDnsRecords": {
        "additionalProperties": false,
        "properties": {
          "dkim": {
            "description": "Three Amazon SES DKIM CNAME records",
            "items": {
              "$ref": "#/components/schemas/MailboxDomainNameValueRecord"
            },
            "type": "array"
          },
          "dmarc": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MailboxDomainNameValueRecord"
              },
              {
                "description": "DMARC enforcement record (quarantine, no reporting)"
              }
            ]
          },
          "mx": {
            "description": "MX records the customer must place. All point at Sendmux's inbound mail servers.",
            "items": {
              "$ref": "#/components/schemas/MailboxDomainMxRecord"
            },
            "type": "array"
          },
          "spf": {
            "$ref": "#/components/schemas/MailboxDomainNameValueRecord"
          },
          "verification": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MailboxDomainNameValueRecord"
              },
              {
                "description": "Ownership-proof TXT record (Sendmux-specific)"
              }
            ]
          }
        },
        "required": [
          "mx",
          "spf",
          "dmarc",
          "dkim",
          "verification"
        ],
        "type": "object"
      },
      "MailboxDomainMxRecord": {
        "additionalProperties": false,
        "properties": {
          "priority": {
            "example": 10,
            "type": "integer"
          },
          "target": {
            "example": "mail.sendmux.ai",
            "type": "string"
          }
        },
        "required": [
          "priority",
          "target"
        ],
        "type": "object"
      },
      "MailboxDomainNameValueRecord": {
        "additionalProperties": false,
        "description": "SPF TXT record covering Amazon SES sending",
        "properties": {
          "name": {
            "example": "_sendmux.acme.com",
            "type": "string"
          },
          "value": {
            "example": "sendmux-verify=team_abc123",
            "type": "string"
          }
        },
        "required": [
          "name",
          "value"
        ],
        "type": "object"
      },
      "MailboxDomainVerifyChecks": {
        "additionalProperties": false,
        "properties": {
          "dmarc": {
            "description": "DMARC TXT record matches expected value",
            "type": "boolean"
          },
          "mx": {
            "description": "MX record present when the domain is configured for receiving. Always true for send-only domains.",
            "type": "boolean"
          },
          "spf": {
            "description": "SPF TXT record matches expected value",
            "type": "boolean"
          },
          "verification_txt": {
            "description": "Ownership TXT record present with correct value",
            "type": "boolean"
          }
        },
        "required": [
          "mx",
          "verification_txt",
          "spf",
          "dmarc"
        ],
        "type": "object"
      },
      "MailboxDomainVerifyResult": {
        "additionalProperties": false,
        "properties": {
          "checks": {
            "$ref": "#/components/schemas/MailboxDomainVerifyChecks"
          },
          "ses_dkim_status": {
            "description": "Latest Amazon SES DKIM status",
            "type": "string"
          },
          "status": {
            "description": "Post-check verification status",
            "enum": [
              "verified",
              "pending"
            ],
            "type": "string"
          }
        },
        "required": [
          "status",
          "ses_dkim_status",
          "checks"
        ],
        "type": "object"
      },
      "MailboxFolder": {
        "additionalProperties": false,
        "properties": {
          "can_add_items": {
            "description": "Whether messages can be moved into this folder.",
            "type": "boolean"
          },
          "id": {
            "description": "Folder ID",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "description": "System role when the folder is a built-in folder.",
            "type": [
              "string",
              "null"
            ]
          },
          "sort_order": {
            "type": [
              "integer",
              "null"
            ]
          },
          "total_messages": {
            "type": "integer"
          },
          "unread_messages": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "parent_id",
          "role",
          "sort_order",
          "total_messages",
          "unread_messages",
          "can_add_items"
        ],
        "type": "object"
      },
      "MailboxFolderCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/MailboxFolder"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxFolderDeletedResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "additionalProperties": false,
                "properties": {
                  "deleted": {
                    "enum": [
                      true
                    ],
                    "type": "boolean"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "deleted",
                  "id"
                ],
                "type": "object"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxFolderQueryChanges": {
        "additionalProperties": false,
        "properties": {
          "added": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string"
                },
                "index": {
                  "type": "integer"
                }
              },
              "required": [
                "id",
                "index"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "new_query_state": {
            "type": "string"
          },
          "old_query_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "removed": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "total": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "old_query_state",
          "new_query_state",
          "has_more",
          "removed",
          "added",
          "total"
        ],
        "type": "object"
      },
      "MailboxFolderQueryChangesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxFolderQueryChanges"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxFolderResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxFolder"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxIdentity": {
        "additionalProperties": false,
        "properties": {
          "bcc": {
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "html_signature": {
            "type": "string"
          },
          "id": {
            "description": "Identity ID",
            "type": "string"
          },
          "may_delete": {
            "description": "Whether the mailbox service allows this identity to be deleted.",
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "reply_to": {
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "text_signature": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "email",
          "reply_to",
          "bcc",
          "text_signature",
          "html_signature",
          "may_delete"
        ],
        "type": "object"
      },
      "MailboxIdentityCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/MailboxIdentity"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxIdentityResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxIdentity"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxItemCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/Mailbox"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxItemResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Mailbox"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxKeyDeletedResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "additionalProperties": false,
                "properties": {
                  "deleted": {
                    "enum": [
                      true
                    ],
                    "type": "boolean"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "deleted",
                  "id"
                ],
                "type": "object"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxMe": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Mailbox"
          },
          {
            "additionalProperties": false,
            "properties": {
              "quota_used_bytes": {
                "description": "Live storage usage in bytes. Omitted when usage is temporarily unavailable.",
                "type": "integer"
              }
            },
            "type": "object"
          }
        ]
      },
      "MailboxMeItemResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxMe"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MailboxMessageSummary"
          },
          {
            "additionalProperties": false,
            "properties": {
              "attachments": {
                "items": {
                  "$ref": "#/components/schemas/MailboxAttachment"
                },
                "type": "array"
              },
              "html_body": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "text_body": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "text_body",
              "html_body",
              "attachments"
            ],
            "type": "object"
          }
        ]
      },
      "MailboxMessageContent": {
        "additionalProperties": false,
        "properties": {
          "attachments": {
            "description": "Attachment metadata only. Attachment contents are not parsed by this endpoint.",
            "items": {
              "$ref": "#/components/schemas/MailboxAttachment"
            },
            "type": "array"
          },
          "body": {
            "additionalProperties": false,
            "properties": {
              "extracted_links": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "format": {
                "enum": [
                  "text",
                  "html"
                ],
                "type": [
                  "string",
                  "null"
                ]
              },
              "html": {
                "description": "HTML body when requested. Returned as a JSON string and not as rendered content.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "is_truncated": {
                "type": "boolean"
              },
              "quotes_stripped": {
                "type": "boolean"
              },
              "signature_stripped": {
                "type": "boolean"
              },
              "text": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "truncated_at_chars": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "format",
              "text",
              "html",
              "is_truncated",
              "truncated_at_chars",
              "signature_stripped",
              "quotes_stripped",
              "extracted_links"
            ],
            "type": "object"
          },
          "dates": {
            "additionalProperties": false,
            "properties": {
              "received_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sent_at": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "received_at",
              "sent_at"
            ],
            "type": "object"
          },
          "headers": {
            "$ref": "#/components/schemas/MailboxContentHeaders"
          },
          "id": {
            "description": "Message ID",
            "type": "string"
          },
          "participants": {
            "additionalProperties": false,
            "properties": {
              "bcc": {
                "items": {
                  "$ref": "#/components/schemas/MailboxAddress"
                },
                "type": "array"
              },
              "cc": {
                "items": {
                  "$ref": "#/components/schemas/MailboxAddress"
                },
                "type": "array"
              },
              "from": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/MailboxAddress"
                  },
                  {
                    "type": [
                      "object",
                      "null"
                    ]
                  }
                ]
              },
              "reply_to": {
                "items": {
                  "$ref": "#/components/schemas/MailboxAddress"
                },
                "type": "array"
              },
              "to": {
                "items": {
                  "$ref": "#/components/schemas/MailboxAddress"
                },
                "type": "array"
              }
            },
            "required": [
              "from",
              "to",
              "cc",
              "bcc",
              "reply_to"
            ],
            "type": "object"
          },
          "states": {
            "additionalProperties": false,
            "properties": {
              "email_state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "option_hash": {
                "type": "string"
              }
            },
            "required": [
              "email_state",
              "option_hash"
            ],
            "type": "object"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "thread_id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "thread_id",
          "subject",
          "participants",
          "dates",
          "body",
          "headers",
          "attachments",
          "states"
        ],
        "type": [
          "object",
          "null"
        ]
      },
      "MailboxMessageContentResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/MailboxMessageContent"
                  },
                  {
                    "type": "object"
                  }
                ]
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxMessageCount": {
        "additionalProperties": false,
        "properties": {
          "sync_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": "integer"
          }
        },
        "required": [
          "total",
          "sync_state"
        ],
        "type": "object"
      },
      "MailboxMessageCountResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxMessageCount"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxMessageDeletedResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "additionalProperties": false,
                "properties": {
                  "deleted": {
                    "enum": [
                      true
                    ],
                    "type": "boolean"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "deleted",
                  "id"
                ],
                "type": "object"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxMessageDetailResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxMessage"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxMessageFlags": {
        "additionalProperties": false,
        "properties": {
          "answered": {
            "type": "boolean"
          },
          "draft": {
            "type": "boolean"
          },
          "flagged": {
            "type": "boolean"
          },
          "seen": {
            "type": "boolean"
          }
        },
        "required": [
          "seen",
          "flagged",
          "draft",
          "answered"
        ],
        "type": "object"
      },
      "MailboxMessageQueryChanges": {
        "additionalProperties": false,
        "properties": {
          "added": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string"
                },
                "index": {
                  "type": "integer"
                }
              },
              "required": [
                "id",
                "index"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "new_query_state": {
            "type": "string"
          },
          "old_query_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "removed": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "total": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "old_query_state",
          "new_query_state",
          "has_more",
          "removed",
          "added",
          "total"
        ],
        "type": "object"
      },
      "MailboxMessageQueryChangesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxMessageQueryChanges"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxMessageSummary": {
        "additionalProperties": false,
        "properties": {
          "bcc": {
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "cc": {
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "flags": {
            "$ref": "#/components/schemas/MailboxMessageFlags"
          },
          "folder_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "from": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MailboxAddress"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "has_attachments": {
            "type": "boolean"
          },
          "id": {
            "description": "Message ID",
            "type": "string"
          },
          "keywords": {
            "description": "Active message keywords, including system flags and custom labels.",
            "example": [
              "$seen",
              "$flagged",
              "agent_triaged"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "preview": {
            "type": [
              "string",
              "null"
            ]
          },
          "received_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "sent_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "size_bytes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "thread_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "to": {
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          }
        },
        "required": [
          "id",
          "thread_id",
          "folder_ids",
          "subject",
          "preview",
          "from",
          "to",
          "cc",
          "bcc",
          "received_at",
          "sent_at",
          "size_bytes",
          "has_attachments",
          "keywords",
          "flags"
        ],
        "type": "object"
      },
      "MailboxMessageSummaryCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/MailboxMessageSummary"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxQuota": {
        "additionalProperties": false,
        "properties": {
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "hard_limit": {
            "type": "integer"
          },
          "id": {
            "description": "Quota ID",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "resource_type": {
            "example": "octets",
            "type": "string"
          },
          "scope": {
            "example": "account",
            "type": "string"
          },
          "soft_limit": {
            "type": [
              "integer",
              "null"
            ]
          },
          "types": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "used": {
            "type": "integer"
          },
          "warn_limit": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "resource_type",
          "used",
          "hard_limit",
          "warn_limit",
          "soft_limit",
          "scope",
          "name",
          "types",
          "description"
        ],
        "type": "object"
      },
      "MailboxQuotaCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/MailboxQuota"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxRawBody": {
        "additionalProperties": false,
        "properties": {
          "body": {
            "additionalProperties": false,
            "properties": {
              "html": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "is_truncated": {
                "type": "boolean"
              },
              "text": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "truncated_at_chars": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "text",
              "html",
              "is_truncated",
              "truncated_at_chars"
            ],
            "type": "object"
          },
          "id": {
            "description": "Message ID",
            "type": "string"
          },
          "part": {
            "enum": [
              "text",
              "html",
              "both"
            ],
            "type": "string"
          },
          "states": {
            "additionalProperties": false,
            "properties": {
              "email_state": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "email_state"
            ],
            "type": "object"
          },
          "thread_id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "thread_id",
          "part",
          "body",
          "states"
        ],
        "type": [
          "object",
          "null"
        ]
      },
      "MailboxRawBodyResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/MailboxRawBody"
                  },
                  {
                    "type": "object"
                  }
                ]
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxRealtimeEvent": {
        "additionalProperties": false,
        "properties": {
          "event_type": {
            "enum": [
              "message.received",
              "message.received.spam",
              "sync_required"
            ],
            "type": "string"
          },
          "is_spam": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "mailbox_id": {
            "type": "string"
          },
          "message": {
            "$ref": "#/components/schemas/MailboxRealtimeMessage"
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "message_id_kind": {
            "enum": [
              "provider",
              "rfc5322"
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "occurred_at": {
            "type": "string"
          },
          "recipients": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "sender": {
            "type": [
              "string",
              "null"
            ]
          },
          "team_public_id": {
            "type": "string"
          }
        },
        "required": [
          "event_type",
          "team_public_id",
          "mailbox_id",
          "message_id",
          "message_id_kind",
          "sender",
          "recipients",
          "is_spam",
          "message",
          "occurred_at"
        ],
        "type": "object"
      },
      "MailboxRealtimeMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MailboxMessageSummary"
          },
          {
            "additionalProperties": false,
            "properties": {
              "attachments": {
                "items": {
                  "$ref": "#/components/schemas/MailboxAttachment"
                },
                "type": "array"
              },
              "body": {
                "additionalProperties": false,
                "properties": {
                  "html": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "is_truncated": {
                    "type": "boolean"
                  },
                  "max_bytes": {
                    "type": "integer"
                  },
                  "text": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "text",
                  "html",
                  "is_truncated",
                  "max_bytes"
                ],
                "type": "object"
              },
              "rfc5322_message_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "rfc5322_message_id",
              "attachments",
              "body"
            ],
            "type": [
              "object",
              "null"
            ]
          }
        ]
      },
      "MailboxSearchSnippet": {
        "additionalProperties": false,
        "properties": {
          "message_id": {
            "type": "string"
          },
          "preview": {
            "description": "Body preview snippet. May include mark tags.",
            "type": [
              "string",
              "null"
            ]
          },
          "subject": {
            "description": "Subject snippet. May include mark tags.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "message_id",
          "subject",
          "preview"
        ],
        "type": "object"
      },
      "MailboxSearchSnippetsResult": {
        "additionalProperties": false,
        "properties": {
          "not_found": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "snippets": {
            "items": {
              "$ref": "#/components/schemas/MailboxSearchSnippet"
            },
            "type": "array"
          },
          "sync_state": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "snippets",
          "not_found",
          "sync_state"
        ],
        "type": "object"
      },
      "MailboxSearchSnippetsResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxSearchSnippetsResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxSendResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/SendMailboxMessageResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxSendScope": {
        "additionalProperties": false,
        "properties": {
          "group_public_ids": {
            "description": "Delivery group public IDs (only when type=group)",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "provider_public_ids": {
            "description": "Provider public IDs (only when type=providers)",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "type": {
            "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.",
            "enum": [
              "all",
              "providers",
              "group"
            ],
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "type": [
          "object",
          "null"
        ]
      },
      "MailboxSession": {
        "additionalProperties": false,
        "properties": {
          "capabilities": {
            "additionalProperties": false,
            "properties": {
              "attachments": {
                "additionalProperties": false,
                "properties": {
                  "download": {
                    "type": "boolean"
                  },
                  "metadata": {
                    "type": "boolean"
                  },
                  "parsing": {
                    "type": "boolean"
                  },
                  "range_download": {
                    "type": "boolean"
                  },
                  "send_with_uploaded_blob": {
                    "type": "boolean"
                  },
                  "upload": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "upload",
                  "download",
                  "range_download",
                  "metadata",
                  "parsing",
                  "send_with_uploaded_blob"
                ],
                "type": "object"
              },
              "folders": {
                "additionalProperties": false,
                "properties": {
                  "changes": {
                    "type": "boolean"
                  },
                  "create": {
                    "type": "boolean"
                  },
                  "delete": {
                    "type": "boolean"
                  },
                  "detail": {
                    "type": "boolean"
                  },
                  "list": {
                    "type": "boolean"
                  },
                  "query_changes": {
                    "type": "boolean"
                  },
                  "update": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "list",
                  "detail",
                  "create",
                  "update",
                  "delete",
                  "changes",
                  "query_changes"
                ],
                "type": "object"
              },
              "identities": {
                "additionalProperties": false,
                "properties": {
                  "changes": {
                    "type": "boolean"
                  },
                  "create": {
                    "type": "boolean"
                  },
                  "delete": {
                    "type": "boolean"
                  },
                  "list": {
                    "type": "boolean"
                  },
                  "update": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "list",
                  "changes",
                  "create",
                  "update",
                  "delete"
                ],
                "type": "object"
              },
              "messages": {
                "additionalProperties": false,
                "properties": {
                  "batch_get": {
                    "type": "boolean"
                  },
                  "batch_update": {
                    "type": "boolean"
                  },
                  "changes": {
                    "type": "boolean"
                  },
                  "clean_content": {
                    "type": "boolean"
                  },
                  "count": {
                    "type": "boolean"
                  },
                  "delete": {
                    "type": "boolean"
                  },
                  "detail": {
                    "type": "boolean"
                  },
                  "keywords": {
                    "type": "boolean"
                  },
                  "list": {
                    "type": "boolean"
                  },
                  "permanent_delete": {
                    "type": "boolean"
                  },
                  "query_changes": {
                    "type": "boolean"
                  },
                  "raw_body": {
                    "type": "boolean"
                  },
                  "search_snippets": {
                    "type": "boolean"
                  },
                  "update_fields": {
                    "items": {
                      "enum": [
                        "seen",
                        "flagged",
                        "keywords"
                      ],
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "list",
                  "detail",
                  "raw_body",
                  "clean_content",
                  "batch_get",
                  "count",
                  "search_snippets",
                  "changes",
                  "query_changes",
                  "update_fields",
                  "keywords",
                  "batch_update",
                  "delete",
                  "permanent_delete"
                ],
                "type": "object"
              },
              "quotas": {
                "additionalProperties": false,
                "properties": {
                  "changes": {
                    "type": "boolean"
                  },
                  "list": {
                    "type": "boolean"
                  },
                  "update": {
                    "type": "boolean"
                  },
                  "usage": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "list",
                  "usage",
                  "changes",
                  "update"
                ],
                "type": "object"
              },
              "submissions": {
                "additionalProperties": false,
                "properties": {
                  "changes": {
                    "type": "boolean"
                  },
                  "detail": {
                    "type": "boolean"
                  },
                  "list": {
                    "type": "boolean"
                  },
                  "send": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "list",
                  "detail",
                  "changes",
                  "send"
                ],
                "type": "object"
              },
              "sync": {
                "additionalProperties": false,
                "properties": {
                  "query_changes": {
                    "items": {
                      "enum": [
                        "messages",
                        "folders"
                      ],
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "typed_changes": {
                    "type": "boolean"
                  },
                  "types": {
                    "items": {
                      "enum": [
                        "messages",
                        "folders",
                        "threads",
                        "submissions",
                        "identities",
                        "quotas"
                      ],
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "typed_changes",
                  "types",
                  "query_changes"
                ],
                "type": "object"
              },
              "threads": {
                "additionalProperties": false,
                "properties": {
                  "changes": {
                    "type": "boolean"
                  },
                  "clean_content": {
                    "type": "boolean"
                  },
                  "detail": {
                    "type": "boolean"
                  },
                  "list": {
                    "type": "boolean"
                  },
                  "messages": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "list",
                  "detail",
                  "messages",
                  "clean_content",
                  "changes"
                ],
                "type": "object"
              }
            },
            "required": [
              "messages",
              "threads",
              "folders",
              "submissions",
              "identities",
              "quotas",
              "attachments",
              "sync"
            ],
            "type": "object"
          },
          "endpoints": {
            "additionalProperties": false,
            "properties": {
              "folders": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "mailbox": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "messages": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "submissions": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "sync": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "threads": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "usage": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "mailbox",
              "messages",
              "threads",
              "folders",
              "submissions",
              "usage",
              "sync"
            ],
            "type": "object"
          },
          "gated": {
            "additionalProperties": false,
            "description": "Flags are true when a feature is intentionally unavailable through the mailbox API.",
            "properties": {
              "attachment_parsing": {
                "type": "boolean"
              },
              "blob_copy": {
                "type": "boolean"
              },
              "blob_lookup": {
                "type": "boolean"
              },
              "events": {
                "type": "boolean"
              },
              "filter_script_writes": {
                "type": "boolean"
              },
              "identity_mutation": {
                "type": "boolean"
              },
              "message_copy": {
                "type": "boolean"
              },
              "message_import": {
                "type": "boolean"
              },
              "message_parse": {
                "type": "boolean"
              },
              "quota_mutation": {
                "type": "boolean"
              },
              "raw_protocol": {
                "type": "boolean"
              },
              "vacation_response": {
                "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"
            ],
            "type": "object"
          },
          "limits": {
            "additionalProperties": false,
            "properties": {
              "attachment_upload_bytes_max": {
                "type": "integer"
              },
              "batch_ids_max": {
                "type": "integer"
              },
              "body_chars_max": {
                "type": "integer"
              },
              "changes_limit_max": {
                "type": "integer"
              },
              "inline_attachment_bytes_max": {
                "type": "integer"
              },
              "keywords_per_update_max": {
                "type": "integer"
              },
              "list_limit_max": {
                "type": "integer"
              },
              "message_body_chars_default": {
                "type": "integer"
              },
              "outbound_raw_message_bytes_max": {
                "type": "integer"
              },
              "thread_body_chars_default": {
                "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"
            ],
            "type": "object"
          },
          "mailbox": {
            "additionalProperties": false,
            "properties": {
              "display_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "email": {
                "example": "agent@example.com",
                "format": "email",
                "type": "string"
              },
              "id": {
                "description": "Mailbox public ID",
                "example": "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
                "type": "string"
              }
            },
            "required": [
              "id",
              "email",
              "display_name"
            ],
            "type": "object"
          },
          "states": {
            "additionalProperties": false,
            "properties": {
              "folders": {
                "type": "string"
              },
              "identities": {
                "type": "string"
              },
              "messages": {
                "type": "string"
              },
              "quotas": {
                "type": "string"
              },
              "submissions": {
                "type": "string"
              },
              "threads": {
                "type": "string"
              }
            },
            "required": [
              "messages",
              "folders",
              "threads",
              "submissions",
              "identities",
              "quotas"
            ],
            "type": "object"
          }
        },
        "required": [
          "mailbox",
          "states",
          "capabilities",
          "limits",
          "gated",
          "endpoints"
        ],
        "type": "object"
      },
      "MailboxSessionResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxSession"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxSubmission": {
        "additionalProperties": false,
        "properties": {
          "delivery_status": {
            "items": {
              "$ref": "#/components/schemas/MailboxSubmissionDeliveryStatus"
            },
            "type": "array"
          },
          "dsn_blob_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "email_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "envelope": {
            "$ref": "#/components/schemas/MailboxSubmissionEnvelope"
          },
          "id": {
            "description": "Submission ID",
            "type": "string"
          },
          "identity_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "mdn_blob_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "send_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "thread_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "undo_status": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "identity_id",
          "email_id",
          "thread_id",
          "send_at",
          "undo_status",
          "envelope",
          "delivery_status",
          "dsn_blob_ids",
          "mdn_blob_ids"
        ],
        "type": "object"
      },
      "MailboxSubmissionCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/MailboxSubmission"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxSubmissionDeliveryStatus": {
        "additionalProperties": false,
        "properties": {
          "delivered": {
            "type": [
              "string",
              "null"
            ]
          },
          "displayed": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "smtp_reply": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "email",
          "smtp_reply",
          "delivered",
          "displayed"
        ],
        "type": "object"
      },
      "MailboxSubmissionEnvelope": {
        "additionalProperties": false,
        "properties": {
          "mail_from": {
            "$ref": "#/components/schemas/MailboxSubmissionEnvelopeAddress"
          },
          "rcpt_to": {
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/MailboxSubmissionEnvelopeAddress"
                },
                {
                  "type": "object"
                }
              ]
            },
            "type": "array"
          }
        },
        "required": [
          "mail_from",
          "rcpt_to"
        ],
        "type": [
          "object",
          "null"
        ]
      },
      "MailboxSubmissionEnvelopeAddress": {
        "additionalProperties": false,
        "properties": {
          "email": {
            "format": "email",
            "type": "string"
          },
          "parameters": {
            "additionalProperties": {
              "type": [
                "string",
                "null"
              ]
            },
            "type": [
              "object",
              "null"
            ]
          }
        },
        "required": [
          "email",
          "parameters"
        ],
        "type": [
          "object",
          "null"
        ]
      },
      "MailboxSubmissionResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxSubmission"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxThread": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MailboxThreadSummary"
          },
          {
            "additionalProperties": false,
            "properties": {
              "message_ids": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "message_ids"
            ],
            "type": "object"
          }
        ]
      },
      "MailboxThreadContentMeta": {
        "additionalProperties": false,
        "properties": {
          "participants": {
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "request_id": {
            "type": "string"
          },
          "states": {
            "additionalProperties": false,
            "properties": {
              "email_state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "option_hash": {
                "type": "string"
              },
              "thread_state": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "thread_state",
              "email_state",
              "option_hash"
            ],
            "type": "object"
          },
          "thread_id": {
            "type": "string"
          }
        },
        "required": [
          "request_id",
          "thread_id",
          "participants",
          "states"
        ],
        "type": "object"
      },
      "MailboxThreadContentResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/MailboxMessageContent"
                    },
                    {
                      "type": "object"
                    }
                  ]
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/MailboxThreadContentMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxThreadDetailResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxThread"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxThreadSummary": {
        "additionalProperties": false,
        "properties": {
          "folder_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "has_attachments": {
            "type": "boolean"
          },
          "id": {
            "description": "Thread ID",
            "type": "string"
          },
          "last_message": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MailboxMessageSummary"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "message_count": {
            "type": "integer"
          },
          "participants": {
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "states": {
            "additionalProperties": false,
            "properties": {
              "email_state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "thread_state": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "thread_state",
              "email_state"
            ],
            "type": "object"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "unread_count": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "subject",
          "message_count",
          "unread_count",
          "has_attachments",
          "folder_ids",
          "participants",
          "last_message",
          "states"
        ],
        "type": "object"
      },
      "MailboxThreadSummaryCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/MailboxThreadSummary"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxTypedChanges": {
        "additionalProperties": false,
        "properties": {
          "types": {
            "additionalProperties": false,
            "properties": {
              "folders": {
                "$ref": "#/components/schemas/MailboxChanges"
              },
              "identities": {
                "$ref": "#/components/schemas/MailboxChanges"
              },
              "messages": {
                "$ref": "#/components/schemas/MailboxChanges"
              },
              "quotas": {
                "$ref": "#/components/schemas/MailboxChanges"
              },
              "submissions": {
                "$ref": "#/components/schemas/MailboxChanges"
              },
              "threads": {
                "$ref": "#/components/schemas/MailboxChanges"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "types"
        ],
        "type": "object"
      },
      "MailboxTypedChangesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxTypedChanges"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "MailboxUsage": {
        "additionalProperties": false,
        "properties": {
          "resources": {
            "items": {
              "$ref": "#/components/schemas/MailboxUsageResource"
            },
            "type": "array"
          },
          "states": {
            "additionalProperties": false,
            "properties": {
              "quota_state": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "quota_state"
            ],
            "type": "object"
          }
        },
        "required": [
          "resources",
          "states"
        ],
        "type": "object"
      },
      "MailboxUsageResource": {
        "additionalProperties": false,
        "properties": {
          "hard_limit": {
            "type": "integer"
          },
          "limit_status": {
            "enum": [
              "ok",
              "warning",
              "soft_limit",
              "hard_limit",
              "unknown"
            ],
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "percent_used": {
            "type": [
              "number",
              "null"
            ]
          },
          "quota_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "soft_limit": {
            "type": [
              "integer",
              "null"
            ]
          },
          "types": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "used": {
            "type": "integer"
          },
          "warn_limit": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "quota_id",
          "name",
          "resource_type",
          "scope",
          "types",
          "used",
          "hard_limit",
          "warn_limit",
          "soft_limit",
          "percent_used",
          "limit_status"
        ],
        "type": "object"
      },
      "MailboxUsageResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MailboxUsage"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "PatchMailboxFolderBody": {
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "sort_order": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PatchMailboxMessageBody": {
        "additionalProperties": false,
        "properties": {
          "flagged": {
            "type": "boolean"
          },
          "keywords": {
            "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
            },
            "type": "object"
          },
          "seen": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "ProviderAllowedActions": {
        "additionalProperties": false,
        "properties": {
          "activate": {
            "type": "boolean"
          },
          "deactivate": {
            "type": "boolean"
          },
          "delete": {
            "type": "boolean"
          },
          "test": {
            "type": "boolean"
          },
          "update": {
            "type": "boolean"
          }
        },
        "required": [
          "update",
          "delete",
          "activate",
          "deactivate",
          "test"
        ],
        "type": "object"
      },
      "ProviderCreateBody": {
        "additionalProperties": false,
        "properties": {
          "from_email": {
            "example": "sender@example.com",
            "format": "email",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "from_name": {
            "example": "Acme",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "example": "Transactional SMTP",
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "percentage": {
            "example": 100,
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "quotas": {
            "additionalProperties": false,
            "properties": {
              "per_day": {
                "anyOf": [
                  {
                    "exclusiveMinimum": 0,
                    "type": "integer"
                  },
                  {
                    "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": [
                  {
                    "exclusiveMinimum": 0,
                    "type": "integer"
                  },
                  {
                    "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": [
                  {
                    "exclusiveMinimum": 0,
                    "type": "integer"
                  },
                  {
                    "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_second": {
                "anyOf": [
                  {
                    "exclusiveMinimum": 0,
                    "type": "integer"
                  },
                  {
                    "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."
              }
            },
            "type": "object"
          },
          "reply_to_email": {
            "example": "support@example.com",
            "format": "email",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "reply_to_name": {
            "example": "Support",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "smtp_host": {
            "example": "smtp.example.com",
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "smtp_password": {
            "example": "smtp-password",
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          },
          "smtp_port": {
            "example": 587,
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "smtp_protocol": {
            "enum": [
              "tls",
              "ssl",
              "none",
              "starttls"
            ],
            "example": "starttls",
            "type": "string"
          },
          "smtp_username": {
            "example": "api-user",
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "tracking_domain": {
            "example": "click.example.com",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "smtp_host",
          "smtp_port",
          "smtp_protocol",
          "smtp_username",
          "smtp_password"
        ],
        "type": "object"
      },
      "ProviderDeleted": {
        "additionalProperties": false,
        "properties": {
          "deleted": {
            "enum": [
              true
            ],
            "type": "boolean"
          },
          "id": {
            "type": "string"
          }
        },
        "required": [
          "deleted",
          "id"
        ],
        "type": "object"
      },
      "ProviderDeletedResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ProviderDeleted"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "ProviderItem": {
        "additionalProperties": false,
        "properties": {
          "allowed_actions": {
            "$ref": "#/components/schemas/ProviderAllowedActions"
          },
          "created_at": {
            "description": "ISO 8601 creation timestamp",
            "example": "2026-05-25T02:18:00Z",
            "type": "string"
          },
          "from_email": {
            "description": "Default From email address.",
            "type": [
              "string",
              "null"
            ]
          },
          "from_name": {
            "description": "Default From display name.",
            "type": [
              "string",
              "null"
            ]
          },
          "has_refresh_token": {
            "description": "Whether an OAuth account has an active connection token.",
            "type": "boolean"
          },
          "has_smtp_password": {
            "description": "Whether a custom SMTP password is stored.",
            "type": "boolean"
          },
          "id": {
            "description": "Sending account public ID",
            "example": "dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "is_active": {
            "description": "Whether this account is enabled for sending.",
            "type": "boolean"
          },
          "is_editable": {
            "description": "False when the account is platform-managed.",
            "type": "boolean"
          },
          "is_shared": {
            "description": "True for the team's shared Amazon SES account.",
            "type": "boolean"
          },
          "last_tested_at": {
            "description": "Last connection test timestamp.",
            "type": [
              "string",
              "null"
            ]
          },
          "last_used_at": {
            "description": "Last send timestamp.",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Display name",
            "example": "Transactional SMTP",
            "type": "string"
          },
          "oauth_email": {
            "description": "Connected account email for OAuth accounts.",
            "type": [
              "string",
              "null"
            ]
          },
          "percentage": {
            "description": "Routing weight percentage.",
            "example": 100,
            "type": [
              "integer",
              "null"
            ]
          },
          "quotas": {
            "$ref": "#/components/schemas/ProviderQuotas"
          },
          "reply_to_email": {
            "description": "Default Reply-To email address.",
            "type": [
              "string",
              "null"
            ]
          },
          "reply_to_name": {
            "description": "Default Reply-To display name.",
            "type": [
              "string",
              "null"
            ]
          },
          "smtp_host": {
            "description": "SMTP host for custom SMTP accounts.",
            "type": [
              "string",
              "null"
            ]
          },
          "smtp_port": {
            "description": "SMTP port for custom SMTP accounts.",
            "type": [
              "integer",
              "null"
            ]
          },
          "smtp_protocol": {
            "description": "SMTP security mode.",
            "type": [
              "string",
              "null"
            ]
          },
          "smtp_username": {
            "description": "SMTP username for custom SMTP accounts.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "description": "Current sending account status.",
            "enum": [
              "active",
              "inactive",
              "error",
              "pending"
            ],
            "example": "active",
            "type": "string"
          },
          "status_reason": {
            "description": "Public-safe reason for the current status.",
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_domain": {
            "description": "Custom tracking hostname.",
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "description": "Sending account type. `amazon_ses` is the shared managed account.",
            "enum": [
              "smtp",
              "gmail_api",
              "outlook_api",
              "amazon_ses"
            ],
            "example": "smtp",
            "type": "string"
          },
          "updated_at": {
            "description": "ISO 8601 last update timestamp",
            "example": "2026-05-25T02:18:00Z",
            "type": "string"
          }
        },
        "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"
        ],
        "type": "object"
      },
      "ProviderItemCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/ProviderItem"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "ProviderItemResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ProviderItem"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "ProviderLimits": {
        "additionalProperties": false,
        "properties": {
          "sending_accounts": {
            "$ref": "#/components/schemas/ResourceLimitSnapshot"
          },
          "shared_amazon_ses": {
            "$ref": "#/components/schemas/SharedAmazonSesLimit"
          }
        },
        "required": [
          "sending_accounts",
          "shared_amazon_ses"
        ],
        "type": "object"
      },
      "ProviderLimitsResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ProviderLimits"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "ProviderQuotaRange": {
        "additionalProperties": false,
        "properties": {
          "max": {
            "example": 60,
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "min": {
            "example": 60,
            "exclusiveMinimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "min",
          "max"
        ],
        "type": [
          "object",
          "null"
        ]
      },
      "ProviderQuotas": {
        "additionalProperties": false,
        "properties": {
          "per_day": {
            "$ref": "#/components/schemas/ProviderQuotaRange"
          },
          "per_hour": {
            "$ref": "#/components/schemas/ProviderQuotaRange"
          },
          "per_minute": {
            "$ref": "#/components/schemas/ProviderQuotaRange"
          },
          "per_second": {
            "$ref": "#/components/schemas/ProviderQuotaRange"
          }
        },
        "required": [
          "per_second",
          "per_minute",
          "per_hour",
          "per_day"
        ],
        "type": "object"
      },
      "ProviderStats": {
        "additionalProperties": false,
        "properties": {
          "active": {
            "description": "Accounts with status 'active'",
            "example": 8,
            "type": "number"
          },
          "by_status": {
            "$ref": "#/components/schemas/ProviderStatusCounts"
          },
          "by_type": {
            "$ref": "#/components/schemas/ProviderTypeCounts"
          },
          "error": {
            "description": "Accounts with status 'error'",
            "example": 1,
            "type": "number"
          },
          "inactive": {
            "description": "Accounts with status 'inactive'",
            "example": 3,
            "type": "number"
          },
          "pending": {
            "description": "Accounts with status 'pending'",
            "example": 0,
            "type": "number"
          },
          "total": {
            "description": "Total number of sending accounts",
            "example": 12,
            "type": "number"
          }
        },
        "required": [
          "total",
          "active",
          "inactive",
          "error",
          "pending",
          "by_type",
          "by_status"
        ],
        "type": "object"
      },
      "ProviderStatsResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ProviderStats"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "ProviderStatusCounts": {
        "additionalProperties": false,
        "properties": {
          "active": {
            "example": 8,
            "type": "number"
          },
          "error": {
            "example": 1,
            "type": "number"
          },
          "inactive": {
            "example": 3,
            "type": "number"
          },
          "pending": {
            "example": 0,
            "type": "number"
          }
        },
        "required": [
          "active",
          "inactive",
          "error",
          "pending"
        ],
        "type": "object"
      },
      "ProviderTestResult": {
        "additionalProperties": false,
        "properties": {
          "latency_ms": {
            "example": 182,
            "minimum": 0,
            "type": "integer"
          },
          "message": {
            "example": "Connection verified.",
            "type": "string"
          },
          "success": {
            "example": true,
            "type": "boolean"
          },
          "tested_at": {
            "example": "2026-05-25T02:18:00Z",
            "type": "string"
          }
        },
        "required": [
          "success",
          "message",
          "latency_ms",
          "tested_at"
        ],
        "type": "object"
      },
      "ProviderTestResultResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ProviderTestResult"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "ProviderTypeCounts": {
        "additionalProperties": false,
        "properties": {
          "amazon_ses": {
            "description": "Number of shared Amazon SES accounts",
            "example": 1,
            "type": "number"
          },
          "gmail_api": {
            "description": "Number of Gmail API accounts",
            "example": 4,
            "type": "number"
          },
          "outlook_api": {
            "description": "Number of Outlook API accounts",
            "example": 2,
            "type": "number"
          },
          "smtp": {
            "description": "Number of SMTP accounts",
            "example": 6,
            "type": "number"
          }
        },
        "required": [
          "smtp",
          "gmail_api",
          "outlook_api",
          "amazon_ses"
        ],
        "type": "object"
      },
      "ProviderUpdateBody": {
        "additionalProperties": false,
        "properties": {
          "from_email": {
            "example": "sender@example.com",
            "format": "email",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "from_name": {
            "example": "Acme",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "example": "Transactional SMTP",
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "percentage": {
            "example": 100,
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "quotas": {
            "additionalProperties": false,
            "properties": {
              "per_day": {
                "anyOf": [
                  {
                    "exclusiveMinimum": 0,
                    "type": "integer"
                  },
                  {
                    "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": [
                  {
                    "exclusiveMinimum": 0,
                    "type": "integer"
                  },
                  {
                    "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": [
                  {
                    "exclusiveMinimum": 0,
                    "type": "integer"
                  },
                  {
                    "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_second": {
                "anyOf": [
                  {
                    "exclusiveMinimum": 0,
                    "type": "integer"
                  },
                  {
                    "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."
              }
            },
            "type": "object"
          },
          "reply_to_email": {
            "example": "support@example.com",
            "format": "email",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "reply_to_name": {
            "example": "Support",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "smtp_host": {
            "example": "smtp.example.com",
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "smtp_password": {
            "example": "new-smtp-password",
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          },
          "smtp_port": {
            "example": 587,
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "smtp_protocol": {
            "enum": [
              "tls",
              "ssl",
              "none",
              "starttls"
            ],
            "example": "starttls",
            "type": "string"
          },
          "smtp_username": {
            "example": "api-user",
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "tracking_domain": {
            "example": "click.example.com",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "ProviderUsage": {
        "additionalProperties": false,
        "properties": {
          "providers": {
            "items": {
              "$ref": "#/components/schemas/ProviderUsageItem"
            },
            "type": "array"
          },
          "window_days": {
            "enum": [
              7
            ],
            "type": "number"
          }
        },
        "required": [
          "window_days",
          "providers"
        ],
        "type": "object"
      },
      "ProviderUsageItem": {
        "additionalProperties": false,
        "properties": {
          "failed_7d": {
            "minimum": 0,
            "type": "integer"
          },
          "pending_7d": {
            "minimum": 0,
            "type": "integer"
          },
          "provider_id": {
            "type": "string"
          },
          "rejected_7d": {
            "minimum": 0,
            "type": "integer"
          },
          "sent_7d": {
            "minimum": 0,
            "type": "integer"
          },
          "sent_today": {
            "minimum": 0,
            "type": "integer"
          },
          "total_7d": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "provider_id",
          "sent_today",
          "total_7d",
          "sent_7d",
          "failed_7d",
          "rejected_7d",
          "pending_7d"
        ],
        "type": "object"
      },
      "ProviderUsageResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ProviderUsage"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "ResourceLimitSnapshot": {
        "additionalProperties": false,
        "properties": {
          "can_request_increase": {
            "type": "boolean"
          },
          "is_at_limit": {
            "type": "boolean"
          },
          "is_near_limit": {
            "type": "boolean"
          },
          "max_allowed": {
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "pending_request_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "reserved": {
            "minimum": 0,
            "type": "integer"
          },
          "resource_type": {
            "example": "sending_accounts",
            "type": "string"
          },
          "threshold_usage": {
            "minimum": 0,
            "type": "integer"
          },
          "usage": {
            "minimum": 0,
            "type": "integer"
          },
          "usage_ratio": {
            "type": "number"
          }
        },
        "required": [
          "resource_type",
          "usage",
          "max_allowed",
          "reserved",
          "threshold_usage",
          "usage_ratio",
          "is_at_limit",
          "is_near_limit",
          "can_request_increase",
          "pending_request_id"
        ],
        "type": "object"
      },
      "ResponseMeta": {
        "additionalProperties": false,
        "properties": {
          "request_id": {
            "example": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          }
        },
        "required": [
          "request_id"
        ],
        "type": "object"
      },
      "SendingAccountLimitRequest": {
        "additionalProperties": false,
        "properties": {
          "limit": {
            "$ref": "#/components/schemas/ResourceLimitSnapshot"
          },
          "request_id": {
            "example": "trir_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          }
        },
        "required": [
          "request_id",
          "limit"
        ],
        "type": "object"
      },
      "SendingAccountLimitRequestResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/SendingAccountLimitRequest"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "SendMailboxMessageBody": {
        "additionalProperties": false,
        "properties": {
          "attachments": {
            "description": "Attachments to send with the message.",
            "items": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "content": {
                      "description": "Base64-encoded content for small inline attachments. Use /mailbox/attachments:upload for larger files.",
                      "type": "string"
                    },
                    "content_type": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "filename",
                    "content_type",
                    "content"
                  ],
                  "type": "object"
                },
                {
                  "additionalProperties": false,
                  "properties": {
                    "blob_id": {
                      "description": "Blob ID returned by /mailbox/attachments:upload.",
                      "type": "string"
                    },
                    "content_type": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "filename",
                    "content_type",
                    "blob_id"
                  ],
                  "type": "object"
                }
              ]
            },
            "type": "array"
          },
          "bcc": {
            "description": "BCC recipients.",
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "cc": {
            "description": "CC recipients.",
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "custom_headers": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Custom headers to include.",
            "type": "object"
          },
          "from": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MailboxAddress"
              },
              {
                "description": "Sender address. Defaults to mailbox identity."
              }
            ]
          },
          "html_body": {
            "description": "HTML body.",
            "type": "string"
          },
          "reply_to": {
            "description": "Reply-To recipients.",
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "type": "array"
          },
          "subject": {
            "description": "Subject line for the outgoing email.",
            "type": "string"
          },
          "text_body": {
            "description": "Plain text body.",
            "type": "string"
          },
          "to": {
            "description": "Primary recipients.",
            "items": {
              "$ref": "#/components/schemas/MailboxAddress"
            },
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "to",
          "subject"
        ],
        "type": "object"
      },
      "SendMailboxMessageResult": {
        "additionalProperties": false,
        "properties": {
          "message_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "queued"
            ],
            "type": "string"
          }
        },
        "required": [
          "message_id",
          "status"
        ],
        "type": "object"
      },
      "SetFilterStateBody": {
        "additionalProperties": false,
        "properties": {
          "mode": {
            "enum": [
              "off",
              "allowlist",
              "denylist"
            ],
            "type": "string"
          },
          "rules": {
            "description": "Replacement rule set. Maximum 1000 rules per request. An empty array is valid (no rules).",
            "items": {
              "$ref": "#/components/schemas/FilterRule"
            },
            "maxItems": 1000,
            "type": "array"
          }
        },
        "required": [
          "mode",
          "rules"
        ],
        "type": "object"
      },
      "SharedAmazonSesLimit": {
        "additionalProperties": false,
        "properties": {
          "can_request_increase": {
            "type": "boolean"
          },
          "daily_limit": {
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "is_near_limit": {
            "type": "boolean"
          },
          "pending_request_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "provider_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "sent_today": {
            "minimum": 0,
            "type": "integer"
          },
          "threshold_usage": {
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "usage_ratio": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "provider_id",
          "daily_limit",
          "sent_today",
          "threshold_usage",
          "usage_ratio",
          "is_near_limit",
          "can_request_increase",
          "pending_request_id"
        ],
        "type": "object"
      },
      "SharedAmazonSesLimitRequest": {
        "additionalProperties": false,
        "properties": {
          "approved_daily_limit": {
            "exclusiveMinimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "current_daily_limit": {
            "minimum": 0,
            "type": "integer"
          },
          "current_daily_sent": {
            "minimum": 0,
            "type": "integer"
          },
          "decided_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "decision_note": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "example": "slir_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "approved",
              "denied",
              "cancelled"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "current_daily_limit",
          "current_daily_sent",
          "approved_daily_limit",
          "decision_note",
          "created_at",
          "decided_at"
        ],
        "type": "object"
      },
      "SharedAmazonSesLimitRequestCancel": {
        "additionalProperties": false,
        "properties": {
          "limit": {
            "$ref": "#/components/schemas/SharedAmazonSesLimit"
          },
          "request": {
            "$ref": "#/components/schemas/SharedAmazonSesLimitRequest"
          }
        },
        "required": [
          "request",
          "limit"
        ],
        "type": "object"
      },
      "SharedAmazonSesLimitRequestCancelResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/SharedAmazonSesLimitRequestCancel"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "SharedAmazonSesLimitRequestCreate": {
        "additionalProperties": false,
        "properties": {
          "limit": {
            "$ref": "#/components/schemas/SharedAmazonSesLimit"
          },
          "request": {
            "$ref": "#/components/schemas/SharedAmazonSesLimitRequest"
          }
        },
        "required": [
          "request",
          "limit"
        ],
        "type": "object"
      },
      "SharedAmazonSesLimitRequestCreateResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/SharedAmazonSesLimitRequestCreate"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "SharedAmazonSesLimitRequestPage": {
        "additionalProperties": false,
        "properties": {
          "limit": {
            "$ref": "#/components/schemas/SharedAmazonSesLimit"
          },
          "pending_request": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SharedAmazonSesLimitRequest"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          }
        },
        "required": [
          "limit",
          "pending_request"
        ],
        "type": "object"
      },
      "SharedAmazonSesLimitRequestPageResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/SharedAmazonSesLimitRequestPage"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "SpendSummary": {
        "additionalProperties": false,
        "properties": {
          "currency": {
            "enum": [
              "USD"
            ],
            "type": "string"
          },
          "period_days": {
            "example": 30,
            "type": "number"
          },
          "total_consumed": {
            "example": "54.770000",
            "type": "string"
          },
          "total_purchased": {
            "example": "150.000000",
            "type": "string"
          },
          "transaction_count": {
            "example": 23,
            "type": "number"
          }
        },
        "required": [
          "period_days",
          "total_purchased",
          "total_consumed",
          "transaction_count",
          "currency"
        ],
        "type": "object"
      },
      "SpendSummaryResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/SpendSummary"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "SuccessEnvelope": {
        "properties": {
          "meta": {
            "additionalProperties": {},
            "properties": {},
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "meta"
        ],
        "type": "object"
      },
      "Transaction": {
        "additionalProperties": false,
        "properties": {
          "amount": {
            "description": "DECIMAL(19,6) amount",
            "example": "-0.001500",
            "type": "string"
          },
          "balance_after": {
            "type": [
              "string",
              "null"
            ]
          },
          "balance_before": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "description": "ISO 8601 timestamp",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "description": "Transaction public ID",
            "example": "tx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "quantity": {
            "description": "Item count (for USAGE transactions)",
            "type": [
              "number",
              "null"
            ]
          },
          "type": {
            "enum": [
              "PURCHASE",
              "USAGE",
              "AUTO_TOPUP",
              "REFUND",
              "ADJUSTMENT"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "amount",
          "type",
          "description",
          "quantity",
          "balance_before",
          "balance_after",
          "created_at"
        ],
        "type": "object"
      },
      "TransactionCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/Transaction"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "UpdateMailboxBody": {
        "additionalProperties": false,
        "properties": {
          "display_name": {
            "description": "Replace the display name; send null to clear it.",
            "maxLength": 254,
            "minLength": 1,
            "type": [
              "string",
              "null"
            ]
          },
          "quota_bytes": {
            "description": "Storage quota in bytes. Allowed values: 1073741824 (1 GB), 5368709120 (5 GB), 53687091200 (50 GB).",
            "example": 5368709120,
            "minimum": 1,
            "type": "integer"
          },
          "send_scope": {
            "additionalProperties": false,
            "description": "Replace outbound routing restrictions.",
            "properties": {
              "group_public_ids": {
                "description": "Delivery group public IDs allowed for sending when type is `group`.",
                "items": {
                  "maxLength": 128,
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              "provider_public_ids": {
                "description": "Provider public IDs allowed for sending when type is `providers`.",
                "items": {
                  "maxLength": 128,
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              "type": {
                "description": "Outbound routing strategy. Use `providers` with provider_public_ids, or `group` with group_public_ids.",
                "enum": [
                  "all",
                  "providers",
                  "group"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          }
        },
        "type": "object"
      },
      "UpdateMailboxIdentityBody": {
        "additionalProperties": false,
        "properties": {
          "html_signature": {
            "description": "HTML signature appended to Mailbox API sends that include html_body.",
            "maxLength": 2047,
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Default sender name. Send null or an empty string to clear it.",
            "maxLength": 254,
            "type": [
              "string",
              "null"
            ]
          },
          "text_signature": {
            "description": "Plain text signature appended to Mailbox API sends that include text_body.",
            "maxLength": 2047,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "WebhookCreateBody": {
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "description": "Defaults to true.",
            "example": true,
            "type": "boolean"
          },
          "event_types": {
            "description": "At least one event type must be provided.",
            "example": [
              "message.bounced",
              "message.received"
            ],
            "items": {
              "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.",
              "enum": [
                "message.delivered",
                "message.bounced",
                "message.complained",
                "message.rejected",
                "message.delivery_delayed",
                "message.received",
                "message.received.spam",
                "sendmux.test"
              ],
              "example": "message.bounced",
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          },
          "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."
              }
            ]
          },
          "name": {
            "description": "Optional human-friendly label (max 255 chars). Surfaced in dashboard list/detail views.",
            "example": "Acme inbound forwarder",
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "url": {
            "description": "HTTPS endpoint that will receive event POSTs. Must be https:// — plain HTTP is rejected.",
            "example": "https://hooks.acme.com/sendmux",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "event_types"
        ],
        "type": "object"
      },
      "WebhookDeletedResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "additionalProperties": false,
                "properties": {
                  "deleted": {
                    "enum": [
                      true
                    ],
                    "type": "boolean"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "deleted",
                  "id"
                ],
                "type": "object"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "WebhookDeliveryAttempt": {
        "additionalProperties": false,
        "properties": {
          "created_at": {
            "description": "ISO 8601 attempt timestamp",
            "example": "2026-05-21T09:12:00Z",
            "type": "string"
          },
          "delivery_attempt": {
            "description": "1-based retry attempt number.",
            "example": 1,
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "error_message": {
            "description": "Public-safe network error category when no HTTP response was received.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "event_id": {
            "description": "Webhook event ID",
            "example": "evt_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "event_type": {
            "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.",
            "enum": [
              "message.delivered",
              "message.bounced",
              "message.complained",
              "message.rejected",
              "message.delivery_delayed",
              "message.received",
              "message.received.spam",
              "sendmux.test"
            ],
            "example": "message.bounced",
            "type": "string"
          },
          "id": {
            "description": "Delivery-attempt public ID",
            "example": "whda_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "max_attempts": {
            "description": "Maximum attempts before the subscription is marked failing.",
            "example": 8,
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "next_retry_at": {
            "description": "Next retry timestamp when result is retrying; otherwise null.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "payload_available": {
            "description": "True while the delivered request payload can still be fetched.",
            "example": true,
            "type": "boolean"
          },
          "payload_expires_at": {
            "description": "Timestamp when the retained request payload expires.",
            "example": "2026-05-28T09:12:00Z",
            "type": "string"
          },
          "request_payload_bytes": {
            "description": "Size of the delivered request payload in bytes.",
            "example": 2048,
            "minimum": 0,
            "type": "integer"
          },
          "request_payload_sha256": {
            "description": "SHA-256 digest of the delivered request payload.",
            "example": "b1946ac92492d2347c6235b4d2611184d4e4f8f2f43a5f2d8d5b7a4a6f0c1e2d",
            "type": [
              "string",
              "null"
            ]
          },
          "response_body": {
            "description": "Truncated endpoint response preview, if any.",
            "example": "ok",
            "type": [
              "string",
              "null"
            ]
          },
          "response_ms": {
            "description": "End-to-end delivery latency in milliseconds.",
            "example": 184,
            "minimum": 0,
            "type": "integer"
          },
          "response_status": {
            "description": "HTTP status returned by the endpoint, or null for network/timeout failures.",
            "example": 200,
            "type": [
              "integer",
              "null"
            ]
          },
          "result": {
            "description": "Delivery result for this attempt.",
            "enum": [
              "success",
              "retrying",
              "failed",
              "permanent_failure"
            ],
            "example": "success",
            "type": "string"
          }
        },
        "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"
        ],
        "type": "object"
      },
      "WebhookDeliveryAttemptCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/WebhookDeliveryAttempt"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "WebhookDeliveryPayload": {
        "additionalProperties": false,
        "properties": {
          "created_at": {
            "description": "ISO 8601 attempt timestamp",
            "example": "2026-05-21T09:12:00Z",
            "type": "string"
          },
          "delivery_attempt": {
            "description": "1-based retry attempt number.",
            "example": 1,
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "event_id": {
            "description": "Webhook event ID",
            "example": "evt_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "event_type": {
            "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.",
            "enum": [
              "message.delivered",
              "message.bounced",
              "message.complained",
              "message.rejected",
              "message.delivery_delayed",
              "message.received",
              "message.received.spam",
              "sendmux.test"
            ],
            "example": "message.bounced",
            "type": "string"
          },
          "expires_at": {
            "description": "Timestamp when this retained payload expires.",
            "example": "2026-05-28T09:12:00Z",
            "type": "string"
          },
          "id": {
            "description": "Delivery-attempt public ID",
            "example": "whda_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "payload": {
            "$ref": "#/components/schemas/WebhookEventPayload"
          }
        },
        "required": [
          "id",
          "event_id",
          "event_type",
          "delivery_attempt",
          "created_at",
          "expires_at",
          "payload"
        ],
        "type": "object"
      },
      "WebhookDeliveryPayloadResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/WebhookDeliveryPayload"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "WebhookEventData": {
        "additionalProperties": false,
        "properties": {
          "bounce_subtype": {
            "description": "More specific bounce category when available.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "bounce_type": {
            "description": "Bounce category for `message.bounced` events.",
            "enum": [
              "Permanent",
              "Transient",
              "Undetermined"
            ],
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "complaint_subtype": {
            "description": "More specific complaint category when available.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "complaint_type": {
            "description": "Complaint category for `message.complained` events.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "delay_expires_at": {
            "description": "When delivery retries are expected to stop, when provided.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "delay_type": {
            "description": "Delay category for `message.delivery_delayed` events.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "is_spam": {
            "description": "Only populated for inbound mailbox events.",
            "example": false,
            "type": [
              "boolean",
              "null"
            ]
          },
          "mailbox_id": {
            "description": "Mailbox public ID for inbound mailbox events when resolved.",
            "example": "mbx_123",
            "type": [
              "string",
              "null"
            ]
          },
          "message_id": {
            "description": "Message identifier from the event source.",
            "example": "ME3P282MB076951B3AAD3255D686EA8EDCA0F2@example.com",
            "type": [
              "string",
              "null"
            ]
          },
          "message_id_kind": {
            "description": "`provider` for sending feedback IDs; `rfc5322` for inbound email Message-ID header values.",
            "enum": [
              "provider",
              "rfc5322"
            ],
            "example": "rfc5322",
            "type": [
              "string",
              "null"
            ]
          },
          "recipients": {
            "description": "All affected recipients. Empty for synthetic test events.",
            "example": [
              "inbox@example.com"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "reject_reason": {
            "description": "Reject reason for `message.rejected` events.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "sender": {
            "description": "Sender/envelope-from address when available.",
            "example": "sender@example.com",
            "type": [
              "string",
              "null"
            ]
          },
          "sendmux_message_id": {
            "description": "Sendmux message correlation ID for outbound sending feedback when available.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "webhook_id": {
            "description": "Target webhook ID for synthetic `sendmux.test` payloads.",
            "example": null,
            "type": [
              "string",
              "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"
        ],
        "type": "object"
      },
      "WebhookEventPayload": {
        "additionalProperties": false,
        "description": "The JSON request body delivered to the webhook endpoint.",
        "example": {
          "data": {
            "bounce_subtype": null,
            "bounce_type": null,
            "complaint_subtype": null,
            "complaint_type": null,
            "delay_expires_at": null,
            "delay_type": null,
            "is_spam": false,
            "mailbox_id": "mbx_123",
            "message_id": "ME3P282MB076951B3AAD3255D686EA8EDCA0F2@example.com",
            "message_id_kind": "rfc5322",
            "recipients": [
              "inbox@example.com"
            ],
            "reject_reason": null,
            "sender": "sender@example.com",
            "sendmux_message_id": null,
            "webhook_id": null
          },
          "id": "evt_clxxxxxxxxxxxxxxxxxxxxxxxxx",
          "occurred_at": "2026-05-21T09:12:00Z",
          "team_public_id": "team_clxxxxxxxxxxxxxxxxxxxxxxxxx",
          "type": "message.received"
        },
        "properties": {
          "data": {
            "$ref": "#/components/schemas/WebhookEventData"
          },
          "id": {
            "description": "Stable per-event identifier. Also sent in the X-Sendmux-Event-Id header.",
            "example": "evt_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "occurred_at": {
            "description": "When the event occurred.",
            "example": "2026-05-21T09:12:00Z",
            "type": "string"
          },
          "team_public_id": {
            "description": "Team that owns the event.",
            "example": "team_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "type": {
            "description": "Dotted event type. Same value as the X-Sendmux-Event-Type header.",
            "enum": [
              "message.delivered",
              "message.bounced",
              "message.complained",
              "message.rejected",
              "message.delivery_delayed",
              "message.received",
              "message.received.spam",
              "sendmux.test"
            ],
            "example": "message.received",
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "team_public_id",
          "occurred_at",
          "data"
        ],
        "type": "object"
      },
      "WebhookFilters": {
        "additionalProperties": false,
        "description": "Optional delivery scope. Empty mailbox_ids means all team mailboxes.",
        "properties": {
          "mailbox_ids": {
            "description": "Mailbox public IDs to receive events for. Empty means all mailboxes in the team.",
            "example": [
              "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "mailbox_ids"
        ],
        "type": "object"
      },
      "WebhookSubscription": {
        "additionalProperties": false,
        "properties": {
          "created_at": {
            "description": "ISO 8601 creation timestamp",
            "example": "2026-04-23T09:12:00Z",
            "type": "string"
          },
          "enabled": {
            "description": "When false, no events are delivered to this subscription.",
            "example": true,
            "type": "boolean"
          },
          "event_types": {
            "description": "Event types this subscription receives.",
            "example": [
              "message.bounced",
              "message.received"
            ],
            "items": {
              "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.",
              "enum": [
                "message.delivered",
                "message.bounced",
                "message.complained",
                "message.rejected",
                "message.delivery_delayed",
                "message.received",
                "message.received.spam",
                "sendmux.test"
              ],
              "example": "message.bounced",
              "type": "string"
            },
            "type": "array"
          },
          "failing": {
            "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,
            "type": "boolean"
          },
          "filters": {
            "$ref": "#/components/schemas/WebhookFilters"
          },
          "id": {
            "description": "Webhook public ID",
            "example": "whk_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          },
          "name": {
            "description": "Optional human-friendly label used in dashboard list/detail pages. May be `null` for subscriptions created without a name.",
            "example": "Acme inbound forwarder",
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "description": "ISO 8601 last-modified timestamp",
            "example": "2026-04-23T09:12:00Z",
            "type": "string"
          },
          "url": {
            "description": "HTTPS endpoint that receives signed event POSTs.",
            "example": "https://hooks.acme.com/sendmux",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "url",
          "event_types",
          "filters",
          "enabled",
          "failing",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "WebhookSubscriptionCursorListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/WebhookSubscription"
                },
                "type": "array"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              },
              "pagination": {
                "$ref": "#/components/schemas/CursorPagination"
              }
            },
            "required": [
              "data",
              "pagination"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "WebhookSubscriptionResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/WebhookSubscription"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "WebhookSubscriptionWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookSubscription"
          },
          {
            "additionalProperties": false,
            "properties": {
              "secret": {
                "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…",
                "type": "string"
              }
            },
            "required": [
              "secret"
            ],
            "type": "object"
          }
        ]
      },
      "WebhookSubscriptionWithSecretResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessEnvelope"
          },
          {
            "properties": {
              "data": {
                "$ref": "#/components/schemas/WebhookSubscriptionWithSecret"
              },
              "meta": {
                "$ref": "#/components/schemas/ResponseMeta"
              }
            },
            "required": [
              "data"
            ],
            "type": "object"
          }
        ],
        "unevaluatedProperties": false
      },
      "WebhookTestResponse": {
        "additionalProperties": false,
        "properties": {
          "event_id": {
            "description": "The event_id attached to the X-Sendmux-Event-Id header of the test delivery.",
            "example": "evt_clxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "string"
          }
        },
        "required": [
          "event_id"
        ],
        "type": "object"
      },
      "WebhookUpdateBody": {
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "description": "When toggled from false to true, also clears the `failing` flag — retry deliveries resume on the next matching event.",
            "type": "boolean"
          },
          "event_types": {
            "description": "Replaces the full event-type list. At least one must be provided.",
            "items": {
              "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.",
              "enum": [
                "message.delivered",
                "message.bounced",
                "message.complained",
                "message.rejected",
                "message.delivery_delayed",
                "message.received",
                "message.received.spam",
                "sendmux.test"
              ],
              "example": "message.bounced",
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          },
          "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."
              }
            ]
          },
          "name": {
            "description": "Replace the human-friendly label. Send `null` to clear it; omit to leave unchanged.",
            "maxLength": 255,
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "description": "New HTTPS endpoint. Must be https://.",
            "format": "uri",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "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.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Programmatic access to your Sendmux email infrastructure.",
    "title": "Sendmux API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/billing/balance": {
      "get": {
        "description": "Returns the current team balance and auto top-up configuration.",
        "operationId": "managementListBalance",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalanceResponse"
                }
              }
            },
            "description": "Current balance"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get current balance",
        "tags": [
          "Billing"
        ]
      }
    },
    "/billing/summary": {
      "get": {
        "description": "Returns a spend summary over a configurable lookback period.",
        "operationId": "managementGetSpendSummary",
        "parameters": [
          {
            "in": "query",
            "name": "days",
            "required": false,
            "schema": {
              "description": "Lookback period in days (default: 30)",
              "enum": [
                "7",
                "30",
                "90"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendSummaryResponse"
                }
              }
            },
            "description": "Spend summary"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get spend summary",
        "tags": [
          "Billing"
        ]
      }
    },
    "/billing/transactions": {
      "get": {
        "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.",
        "operationId": "managementListTransactions",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Max results (default 25, max 100)",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "enum": [
                "PURCHASE",
                "USAGE",
                "AUTO_TOPUP",
                "REFUND",
                "ADJUSTMENT"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionCursorListResponse"
                }
              }
            },
            "description": "Transaction list"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List transactions",
        "tags": [
          "Billing"
        ]
      }
    },
    "/domains": {
      "get": {
        "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.",
        "operationId": "managementListDomains",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100)",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainItemCursorListResponse"
                }
              }
            },
            "description": "Domain list"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mailbox domains",
        "tags": [
          "Domains"
        ]
      },
      "post": {
        "description": "Creates a new domain and returns the DNS records the customer must place before verification can succeed. `send_only` configures outbound sending without changing MX records. `send_receive` also configures the domain for hosted mailboxes. Provisioning touches our email platform and Amazon SES; on any failure the partial state is automatically rolled back.\n\nSupply an `Idempotency-Key` header (any unique string, max 255 chars) to safely retry on network errors. Replays with the same key return the original response; replays with a different body return `409 idempotency_conflict`.",
        "operationId": "managementCreateDomain",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "domain": {
                    "description": "Fully qualified domain name. Must be lowercased and domain-only (no scheme).",
                    "example": "mail.acme.com",
                    "type": "string"
                  },
                  "mode": {
                    "description": "Domain usage mode. Defaults to `send_receive` when omitted.",
                    "enum": [
                      "send_only",
                      "send_receive"
                    ],
                    "example": "send_only",
                    "type": "string"
                  }
                },
                "required": [
                  "domain"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainItemResponse"
                }
              }
            },
            "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": {
                  "example": "/api/v1/domains/mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain already in use, or `Idempotency-Key` was replayed with a different body."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "SES tenant not yet provisioned for this team"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a mailbox domain",
        "tags": [
          "Domains"
        ]
      }
    },
    "/domains/{public_id}": {
      "delete": {
        "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.",
        "operationId": "managementDeleteDomain",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Domain public ID",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainDeletedResponse"
                }
              }
            },
            "description": "Deletion result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain still has active mailboxes (error code `conflict`)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a mailbox domain",
        "tags": [
          "Domains"
        ]
      },
      "get": {
        "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.",
        "operationId": "managementGetDomain",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Domain public ID",
              "example": "mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainItemResponse"
                }
              }
            },
            "description": "Domain",
            "headers": {
              "ETag": {
                "description": "Weak ETag for conditional GETs.",
                "schema": {
                  "example": "W/\"a1b2c3d4e5f60718\"",
                  "type": "string"
                }
              }
            }
          },
          "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": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a mailbox domain",
        "tags": [
          "Domains"
        ]
      },
      "patch": {
        "description": "Upgrades a send-only domain to sending and receiving. Downgrades are rejected. After upgrade, the domain returns to `pending` until the required MX record verifies.",
        "operationId": "managementUpdateDomain",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Domain public ID",
              "example": "mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs.",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "mode": {
                    "description": "The only supported update is upgrading to `send_receive`.",
                    "enum": [
                      "send_receive"
                    ],
                    "example": "send_receive",
                    "type": "string"
                  }
                },
                "required": [
                  "mode"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainItemResponse"
                }
              }
            },
            "description": "Updated domain",
            "headers": {
              "ETag": {
                "description": "Weak ETag for the post-update resource.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "`If-Match` mismatch, or the domain cannot be upgraded in its current state."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Unsupported update. Only `{ mode: \"send_receive\" }` is accepted."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a mailbox domain",
        "tags": [
          "Domains"
        ]
      }
    },
    "/domains/{public_id}/filters": {
      "get": {
        "description": "Returns the current sender-filter mode and rule set applied to every mailbox under this domain. Only sending and receiving domains support domain-wide filters. Per-mailbox rules take precedence at match time.\n\nResponses carry a weak `ETag` — send it as `If-None-Match` to skip the body when the filter set has not changed (returns `304 Not Modified`). The same ETag is the value to use in `If-Match` on the corresponding PUT for optimistic concurrency.",
        "operationId": "managementGetDomainFilters",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Domain public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilterStateResponse"
                }
              }
            },
            "description": "Filter state",
            "headers": {
              "ETag": {
                "description": "Weak ETag for conditional GETs and optimistic-concurrency PUTs.",
                "schema": {
                  "example": "W/\"a1b2c3d4e5f60718\"",
                  "type": "string"
                }
              }
            }
          },
          "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": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain is send-only and does not support inbound filters."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Filter service temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get domain-wide sender filters",
        "tags": [
          "Domain Filters"
        ]
      },
      "put": {
        "description": "Atomically replaces the sender-filter mode and rule set for an entire sending and receiving domain. Applies to every mailbox under the domain unless that mailbox has its own per-mailbox rules (which take precedence). Maximum 1000 rules per request.\n\nFor optimistic concurrency, send `If-Match: <etag>` using the ETag from a prior GET. A mismatched `If-Match` returns `409 conflict` (the server's ETag is echoed back so you can decide whether to re-fetch). Responses carry the new ETag so chained edits can pipeline without a re-GET.",
        "operationId": "managementSetDomainFilters",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Domain public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs.",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetFilterStateBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilterStateResponse"
                }
              }
            },
            "description": "Updated filter state",
            "headers": {
              "ETag": {
                "description": "Weak ETag for the post-update resource.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "`If-Match` ETag does not match the server's current version, or the domain is send-only."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Rule cap exceeded or invalid rule pattern"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Filter service temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace domain-wide sender filters",
        "tags": [
          "Domain Filters"
        ]
      }
    },
    "/domains/{public_id}/verify": {
      "post": {
        "description": "Runs an immediate DNS-over-HTTPS check of the domain's required DNS records, then asks Amazon SES for the latest DKIM status. If every required 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.",
        "operationId": "managementVerifyDomain",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Domain public ID",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainVerifyResponse"
                }
              }
            },
            "description": "Verification result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Verify a mailbox domain",
        "tags": [
          "Domains"
        ]
      }
    },
    "/domains/{public_id}/zone-file": {
      "get": {
        "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.",
        "operationId": "managementGetDomainZoneFile",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Domain public ID",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Zone file (text/plain)",
            "headers": {
              "Content-Disposition": {
                "description": "Attachment filename `<domain>.zone`.",
                "schema": {
                  "example": "attachment; filename=\"mail.acme.com.zone\"",
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a domain as a zone file",
        "tags": [
          "Domains"
        ]
      }
    },
    "/emails/logs": {
      "get": {
        "description": "Returns paginated delivery logs with cursor-based pagination and filters.",
        "operationId": "managementListEmailLogs",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Max results (default 25)",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Cursor from previous page",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "description": "Filter by delivery status.",
              "enum": [
                "pending",
                "sent",
                "failed",
                "rejected"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from_date",
            "required": false,
            "schema": {
              "description": "ISO 8601 start date. Date-only values start at 00:00 UTC.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to_date",
            "required": false,
            "schema": {
              "description": "ISO 8601 end date. Date-only values include the full UTC day.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "provider_id",
            "required": false,
            "schema": {
              "description": "Filter by provider publicId",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "search",
            "required": false,
            "schema": {
              "description": "Search to_email, from_email, sent_from_email, subject, message_id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryLogItemCursorListResponse"
                }
              }
            },
            "description": "Delivery log list"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List delivery logs",
        "tags": [
          "Emails"
        ]
      }
    },
    "/emails/logs/{public_id}": {
      "get": {
        "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.",
        "operationId": "managementGetEmailLog",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Delivery log public ID (dlog_...)",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryLogItemResponse"
                }
              }
            },
            "description": "Delivery log detail",
            "headers": {
              "ETag": {
                "description": "Weak ETag for conditional GETs.",
                "schema": {
                  "example": "W/\"a1b2c3d4e5f60718\"",
                  "type": "string"
                }
              }
            }
          },
          "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": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get delivery log",
        "tags": [
          "Emails"
        ]
      }
    },
    "/emails/metrics": {
      "get": {
        "description": "Returns aggregated email delivery counts with flexible time windowing and comparison period.",
        "operationId": "managementGetEmailMetrics",
        "parameters": [
          {
            "in": "query",
            "name": "window",
            "required": false,
            "schema": {
              "description": "Preset time window (default: 24h)",
              "enum": [
                "24h",
                "7d",
                "30d"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from_date",
            "required": false,
            "schema": {
              "description": "ISO 8601 start date (overrides window)",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to_date",
            "required": false,
            "schema": {
              "description": "ISO 8601 end date",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "granularity",
            "required": false,
            "schema": {
              "description": "Timeseries granularity (default: daily)",
              "enum": [
                "hourly",
                "daily"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "provider_id",
            "required": false,
            "schema": {
              "description": "Filter by provider publicId",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailMetricsResponse"
                }
              }
            },
            "description": "Email metrics with comparison"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get email metrics",
        "tags": [
          "Emails"
        ]
      }
    },
    "/inboxes/logs": {
      "get": {
        "description": "Returns paginated incoming message logs for billing accountability.",
        "operationId": "managementListInboxLogs",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Max results (default 25)",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Cursor from previous page",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "description": "Filter by mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "event_type",
            "required": false,
            "schema": {
              "enum": [
                "message.received",
                "message.received.spam"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from_date",
            "required": false,
            "schema": {
              "description": "ISO 8601 start date. Date-only values start at 00:00 UTC.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to_date",
            "required": false,
            "schema": {
              "description": "ISO 8601 end date. Date-only values include the full UTC day.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "search",
            "required": false,
            "schema": {
              "description": "Search mailbox, sender, recipient, subject, or message ID",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IncomingLogItemCursorListResponse"
                }
              }
            },
            "description": "Incoming log list"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List incoming logs",
        "tags": [
          "Inboxes"
        ]
      }
    },
    "/inboxes/logs/{public_id}": {
      "get": {
        "description": "Returns one incoming message log by public ID.",
        "operationId": "managementGetInboxLog",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Incoming log public ID (ilog_...)",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IncomingLogItemResponse"
                }
              }
            },
            "description": "Incoming log detail"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get incoming log",
        "tags": [
          "Inboxes"
        ]
      }
    },
    "/mailbox/attachments:upload": {
      "post": {
        "description": "Uploads one attachment as binary data and returns a blob ID that can be supplied to `POST /mailbox/messages/send`.",
        "operationId": "mailboxUploadAttachment",
        "parameters": [
          {
            "in": "query",
            "name": "filename",
            "required": true,
            "schema": {
              "description": "Filename to use when sending the uploaded attachment.",
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "description": "Raw attachment bytes.",
                "format": "binary",
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxAttachmentUploadResultResponse"
                }
              }
            },
            "description": "Attachment uploaded"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid upload request"
          },
          "413": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Attachment too large"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox service unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload a mailbox attachment",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/changes": {
      "get": {
        "description": "Returns message changes in the legacy shape when `types` is omitted. Pass a comma-separated `types` list for a typed state map.",
        "operationId": "mailboxGetChanges",
        "parameters": [
          {
            "in": "query",
            "name": "since_state",
            "required": false,
            "schema": {
              "description": "Legacy message state cursor to resume from.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "types",
            "required": false,
            "schema": {
              "description": "Comma-separated list: messages, folders, threads, submissions, identities, quotas.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "messages_since_state",
            "required": false,
            "schema": {
              "description": "Message state cursor to resume from.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "folders_since_state",
            "required": false,
            "schema": {
              "description": "Folder state cursor to resume from.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "threads_since_state",
            "required": false,
            "schema": {
              "description": "Thread state cursor to resume from.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "submissions_since_state",
            "required": false,
            "schema": {
              "description": "Submission state cursor to resume from.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "identities_since_state",
            "required": false,
            "schema": {
              "description": "Identity state cursor to resume from.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "quotas_since_state",
            "required": false,
            "schema": {
              "description": "Quota state cursor to resume from.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum change records to return (default 50, max 500).",
              "maximum": 500,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/MailboxChangesResponse"
                    },
                    {
                      "$ref": "#/components/schemas/MailboxTypedChangesResponse"
                    }
                  ]
                }
              }
            },
            "description": "Mailbox changes"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid sync state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get mailbox changes",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/events": {
      "get": {
        "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.",
        "operationId": "mailboxStreamEvents",
        "parameters": [
          {
            "in": "query",
            "name": "event_types",
            "required": false,
            "schema": {
              "description": "Comma-separated list: message.received, message.received.spam.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "last_event_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "ping",
            "required": false,
            "schema": {
              "maximum": 300,
              "minimum": 10,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "close_after",
            "required": false,
            "schema": {
              "maximum": 3600,
              "minimum": 30,
              "type": "integer"
            }
          },
          {
            "in": "header",
            "name": "Last-Event-ID",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxRealtimeEvent"
                }
              }
            },
            "description": "Server-sent event stream. Event data uses the MailboxRealtimeEvent shape."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid stream parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox API key required"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Too many realtime connections"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Realtime events unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Stream mailbox events",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/folders": {
      "get": {
        "description": "Returns a cursor-paginated list of folders for the authenticated mailbox.",
        "operationId": "mailboxListFolders",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100).",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxFolderCursorListResponse"
                }
              }
            },
            "description": "Folder list"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mailbox folders",
        "tags": [
          "Mailbox API"
        ]
      },
      "post": {
        "description": "Creates a folder in the authenticated mailbox.",
        "operationId": "mailboxCreateFolder",
        "parameters": [
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMailboxFolderBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxFolderResponse"
                }
              }
            },
            "description": "Folder created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Folder validation failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a mailbox folder",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/folders/{folder_id}": {
      "delete": {
        "description": "Deletes an empty custom folder unconditionally unless `If-Match` is supplied. Built-in folders and non-empty folders cannot be deleted. Send `If-Match` with a prior ETag to reject stale deletes.",
        "operationId": "mailboxDeleteFolder",
        "parameters": [
          {
            "in": "path",
            "name": "folder_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxFolderDeletedResponse"
                }
              }
            },
            "description": "Deletion result"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Folder cannot be deleted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a mailbox folder",
        "tags": [
          "Mailbox API"
        ]
      },
      "get": {
        "description": "Returns one folder from the authenticated mailbox. Responses include a weak `ETag` header.",
        "operationId": "mailboxGetFolder",
        "parameters": [
          {
            "in": "path",
            "name": "folder_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxFolderResponse"
                }
              }
            },
            "description": "Folder"
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Folder not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a mailbox folder",
        "tags": [
          "Mailbox API"
        ]
      },
      "patch": {
        "description": "Updates a folder unconditionally unless `If-Match` is supplied. Send `If-Match` with a prior ETag to reject stale edits.",
        "operationId": "mailboxUpdateFolder",
        "parameters": [
          {
            "in": "path",
            "name": "folder_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchMailboxFolderBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxFolderResponse"
                }
              }
            },
            "description": "Updated folder"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Folder not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "ETag conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a mailbox folder",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/folders/changes": {
      "get": {
        "description": "Returns folder changes since a prior folder state, or the current folder state when omitted.",
        "operationId": "mailboxGetFolderChanges",
        "parameters": [
          {
            "in": "query",
            "name": "since_state",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 500,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxChangesResponse"
                }
              }
            },
            "description": "Folder changes"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid sync state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get folder changes",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/folders/query-changes": {
      "get": {
        "description": "Returns folder-list index changes since a prior folder query state, or the current folder query state when omitted.",
        "operationId": "mailboxQueryFolderChanges",
        "parameters": [
          {
            "in": "query",
            "name": "since_query_state",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 500,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxFolderQueryChangesResponse"
                }
              }
            },
            "description": "Folder query changes"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query sync state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get folder query changes",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/identities": {
      "get": {
        "description": "Returns sender identities available to the authenticated mailbox.",
        "operationId": "mailboxListIdentities",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100).",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxIdentityCursorListResponse"
                }
              }
            },
            "description": "Identity list"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox API key required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mailbox sender identities",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/identity": {
      "get": {
        "description": "Returns the default sender identity and signatures for the authenticated mailbox.",
        "operationId": "mailboxGetIdentity",
        "parameters": [
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxIdentityResponse"
                }
              }
            },
            "description": "Mailbox sender identity"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox API key required"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox service unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get mailbox sender identity",
        "tags": [
          "Mailbox API"
        ]
      },
      "patch": {
        "description": "Updates the default sender name, plain text signature, and HTML signature for the authenticated mailbox.",
        "operationId": "mailboxUpdateIdentity",
        "parameters": [
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateMailboxIdentityBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxIdentityResponse"
                }
              }
            },
            "description": "Updated mailbox sender identity"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox API key required"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Identity could not be updated"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox service unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update mailbox sender identity",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/mailboxes": {
      "get": {
        "description": "Lists the mailboxes available to the current mailbox credential or connected app. Use this before choosing a `mailbox_id` for mailbox actions when more than one mailbox is available.",
        "operationId": "mailboxListGrantedMailboxes",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Cursor from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50).",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "description": "Search by mailbox ID or email address.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrantedMailboxListResponse"
                }
              }
            },
            "description": "Granted mailboxes"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox access required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List granted mailboxes",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/me": {
      "get": {
        "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.",
        "operationId": "mailboxGetMe",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMeItemResponse"
                }
              }
            },
            "description": "The calling mailbox",
            "headers": {
              "ETag": {
                "description": "Weak ETag for conditional GETs.",
                "schema": {
                  "example": "W/\"a1b2c3d4e5f60718\"",
                  "type": "string"
                }
              }
            }
          },
          "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": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Root key used on a mailbox-scoped endpoint"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Self-introspect the calling mailbox",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages": {
      "get": {
        "description": "Returns a cursor-paginated list of messages for the authenticated mailbox. Requires a mailbox API key.",
        "operationId": "mailboxListMessages",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100).",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "folder_id",
            "required": false,
            "schema": {
              "description": "Filter to messages in this folder ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "thread_id",
            "required": false,
            "schema": {
              "description": "Filter to messages in this thread ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "description": "Full-text search query across message fields.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "description": "Filter by sender email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "description": "Filter by To recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cc",
            "required": false,
            "schema": {
              "description": "Filter by CC recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "bcc",
            "required": false,
            "schema": {
              "description": "Filter by BCC recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "subject",
            "required": false,
            "schema": {
              "description": "Filter by subject text.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "body",
            "required": false,
            "schema": {
              "description": "Filter by message body text.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "header_name",
            "required": false,
            "schema": {
              "description": "Header name to match with `header_value`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "header_value",
            "required": false,
            "schema": {
              "description": "Header value to match with `header_name`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "min_size_bytes",
            "required": false,
            "schema": {
              "description": "Minimum message size in bytes.",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "max_size_bytes",
            "required": false,
            "schema": {
              "description": "Maximum message size in bytes.",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "keyword",
            "required": false,
            "schema": {
              "description": "Require this message keyword, such as `$seen`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "not_keyword",
            "required": false,
            "schema": {
              "description": "Exclude messages with this keyword.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "description": "Filter to messages after this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "description": "Filter to messages before this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "has_attachment",
            "required": false,
            "schema": {
              "description": "When true, only return messages with attachments.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "is_unread",
            "required": false,
            "schema": {
              "description": "When true, only return unread messages.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "sort_by",
            "required": false,
            "schema": {
              "description": "Message field to sort by.",
              "enum": [
                "received_at",
                "sent_at",
                "subject",
                "from",
                "to",
                "size_bytes"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_direction",
            "required": false,
            "schema": {
              "description": "Sort direction.",
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMessageSummaryCursorListResponse"
                }
              }
            },
            "description": "Message list"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox API key required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mailbox messages",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages:batch-delete": {
      "post": {
        "description": "Moves up to 100 messages to Trash by default with state-safe conflict handling. Set `permanent=true` to permanently delete them.",
        "operationId": "mailboxBatchDeleteMessages",
        "parameters": [
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchDeleteMailboxMessagesBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxBatchDeleteMessagesResultResponse"
                }
              }
            },
            "description": "Batch delete result"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "State conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Batch delete mailbox messages",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages:batch-get": {
      "post": {
        "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.",
        "operationId": "mailboxBatchGetMessages",
        "parameters": [
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MailboxBatchGetBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxBatchGetResultResponse"
                }
              }
            },
            "description": "Batch message result"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Message not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Batch get mailbox messages",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages:batch-update": {
      "post": {
        "description": "Updates allowed message flags and keywords for up to 100 messages with state-safe conflict handling.",
        "operationId": "mailboxBatchUpdateMessages",
        "parameters": [
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchUpdateMailboxMessagesBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxBatchUpdateMessagesResultResponse"
                }
              }
            },
            "description": "Batch update result"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "State conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Batch update mailbox messages",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages/{message_id}": {
      "delete": {
        "description": "Moves a message to Trash by default, unconditionally unless `If-Match` is supplied. Set `permanent=true` to permanently delete it. Send `If-Match` with a prior ETag to reject stale deletes.",
        "operationId": "mailboxDeleteMessage",
        "parameters": [
          {
            "in": "path",
            "name": "message_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "permanent",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMessageDeletedResponse"
                }
              }
            },
            "description": "Deletion result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Message not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "ETag or state conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a mailbox message",
        "tags": [
          "Mailbox API"
        ]
      },
      "get": {
        "description": "Returns one message from the authenticated mailbox. Responses include a weak `ETag` header.",
        "operationId": "mailboxGetMessage",
        "parameters": [
          {
            "in": "path",
            "name": "message_id",
            "required": true,
            "schema": {
              "description": "Message ID.",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMessageDetailResponse"
                }
              }
            },
            "description": "Message"
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Message not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a mailbox message",
        "tags": [
          "Mailbox API"
        ]
      },
      "patch": {
        "description": "Updates mutable message flags and keywords unconditionally unless `If-Match` is supplied. Send `If-Match` with a prior ETag to reject stale edits.",
        "operationId": "mailboxUpdateMessage",
        "parameters": [
          {
            "in": "path",
            "name": "message_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchMailboxMessageBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMessageDetailResponse"
                }
              }
            },
            "description": "Updated message"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Message not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "ETag conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update mailbox message flags",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages/{message_id}/attachments/{attachment_id}": {
      "get": {
        "description": "Streams one attachment from a message in the authenticated mailbox. Supports standard byte ranges.",
        "operationId": "mailboxGetMessageAttachment",
        "parameters": [
          {
            "in": "path",
            "name": "message_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "attachment_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Range",
            "required": false,
            "schema": {
              "description": "Optional byte range, for example `bytes=0-1048575`.",
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Attachment bytes"
          },
          "206": {
            "description": "Partial attachment bytes"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid range header"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Attachment not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a message attachment",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages/{message_id}/body": {
      "get": {
        "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.",
        "operationId": "mailboxListBody",
        "parameters": [
          {
            "in": "path",
            "name": "message_id",
            "required": true,
            "schema": {
              "description": "Message ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "part",
            "required": false,
            "schema": {
              "description": "Body part to return.",
              "enum": [
                "text",
                "html",
                "both"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "max_body_chars",
            "required": false,
            "schema": {
              "description": "Maximum body characters to return before truncation.",
              "maximum": 1000000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxRawBodyResponse"
                }
              }
            },
            "description": "Raw message body"
          },
          "304": {
            "description": "Not modified"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Message not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get raw message body",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages/{message_id}/content": {
      "get": {
        "description": "Returns deterministic clean JSON content for one message. Attachment output is metadata only; attachment contents are not parsed by this endpoint.",
        "operationId": "mailboxListContent",
        "parameters": [
          {
            "in": "path",
            "name": "message_id",
            "required": true,
            "schema": {
              "description": "Message ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "part",
            "required": false,
            "schema": {
              "description": "Body part to return. `auto` prefers text when available.",
              "enum": [
                "auto",
                "text",
                "html"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "max_body_chars",
            "required": false,
            "schema": {
              "description": "Maximum body characters to return before truncation.",
              "maximum": 1000000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "strip_signature",
            "required": false,
            "schema": {
              "description": "When true, remove detected email signatures.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "strip_quotes",
            "required": false,
            "schema": {
              "description": "When true, remove quoted reply text.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_links",
            "required": false,
            "schema": {
              "description": "When true, include links extracted from the body.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_html",
            "required": false,
            "schema": {
              "description": "When true, include HTML content when available.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_headers",
            "required": false,
            "schema": {
              "description": "Header detail to include in the response.",
              "enum": [
                "none",
                "selected",
                "full"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include_attachments",
            "required": false,
            "schema": {
              "description": "Attachment detail to include. Contents are not returned.",
              "enum": [
                "none",
                "metadata"
              ],
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMessageContentResponse"
                }
              }
            },
            "description": "Clean message content"
          },
          "304": {
            "description": "Not modified"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Message not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get clean message content",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages/count": {
      "get": {
        "description": "Returns a count for the supplied mailbox message filters without returning message rows.",
        "operationId": "mailboxCountMessages",
        "parameters": [
          {
            "in": "query",
            "name": "folder_id",
            "required": false,
            "schema": {
              "description": "Filter to messages in this folder ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "thread_id",
            "required": false,
            "schema": {
              "description": "Filter to messages in this thread ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "description": "Full-text search query across message fields.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "description": "Filter by sender email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "description": "Filter by To recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cc",
            "required": false,
            "schema": {
              "description": "Filter by CC recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "bcc",
            "required": false,
            "schema": {
              "description": "Filter by BCC recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "subject",
            "required": false,
            "schema": {
              "description": "Filter by subject text.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "body",
            "required": false,
            "schema": {
              "description": "Filter by message body text.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "header_name",
            "required": false,
            "schema": {
              "description": "Header name to match with `header_value`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "header_value",
            "required": false,
            "schema": {
              "description": "Header value to match with `header_name`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "min_size_bytes",
            "required": false,
            "schema": {
              "description": "Minimum message size in bytes.",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "max_size_bytes",
            "required": false,
            "schema": {
              "description": "Maximum message size in bytes.",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "keyword",
            "required": false,
            "schema": {
              "description": "Require this message keyword, such as `$seen`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "not_keyword",
            "required": false,
            "schema": {
              "description": "Exclude messages with this keyword.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "description": "Filter to messages after this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "description": "Filter to messages before this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "has_attachment",
            "required": false,
            "schema": {
              "description": "When true, only return messages with attachments.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "is_unread",
            "required": false,
            "schema": {
              "description": "When true, only return unread messages.",
              "type": "boolean"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMessageCountResponse"
                }
              }
            },
            "description": "Message count"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Count mailbox messages",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages/query-changes": {
      "get": {
        "description": "Returns filtered message-list index changes since a prior message query state, or the current message query state when omitted.",
        "operationId": "mailboxQueryMessageChanges",
        "parameters": [
          {
            "in": "query",
            "name": "since_query_state",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 500,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "up_to_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "calculate_total",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "folder_id",
            "required": false,
            "schema": {
              "description": "Filter to messages in this folder ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "description": "Full-text search query across message fields.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "description": "Filter by sender email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "description": "Filter by To recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cc",
            "required": false,
            "schema": {
              "description": "Filter by CC recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "bcc",
            "required": false,
            "schema": {
              "description": "Filter by BCC recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "subject",
            "required": false,
            "schema": {
              "description": "Filter by subject text.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "body",
            "required": false,
            "schema": {
              "description": "Filter by message body text.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "header_name",
            "required": false,
            "schema": {
              "description": "Header name to match with `header_value`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "header_value",
            "required": false,
            "schema": {
              "description": "Header value to match with `header_name`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "min_size_bytes",
            "required": false,
            "schema": {
              "description": "Minimum message size in bytes.",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "max_size_bytes",
            "required": false,
            "schema": {
              "description": "Maximum message size in bytes.",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "keyword",
            "required": false,
            "schema": {
              "description": "Require this message keyword, such as `$seen`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "not_keyword",
            "required": false,
            "schema": {
              "description": "Exclude messages with this keyword.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "description": "Filter to messages after this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "description": "Filter to messages before this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "has_attachment",
            "required": false,
            "schema": {
              "description": "When true, only return messages with attachments.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "is_unread",
            "required": false,
            "schema": {
              "description": "When true, only return unread messages.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "sort_by",
            "required": false,
            "schema": {
              "enum": [
                "received_at",
                "sent_at",
                "subject",
                "from",
                "to",
                "size_bytes"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_direction",
            "required": false,
            "schema": {
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMessageQueryChangesResponse"
                }
              }
            },
            "description": "Message query changes"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query sync state or filter"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get message query changes",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages/search-snippets": {
      "get": {
        "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.",
        "operationId": "mailboxSearchMessageSnippets",
        "parameters": [
          {
            "in": "query",
            "name": "folder_id",
            "required": false,
            "schema": {
              "description": "Filter to messages in this folder ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "description": "Filter by sender email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "description": "Filter by To recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cc",
            "required": false,
            "schema": {
              "description": "Filter by CC recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "bcc",
            "required": false,
            "schema": {
              "description": "Filter by BCC recipient email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "subject",
            "required": false,
            "schema": {
              "description": "Filter by subject text.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "body",
            "required": false,
            "schema": {
              "description": "Filter by message body text.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "header_name",
            "required": false,
            "schema": {
              "description": "Header name to match with `header_value`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "header_value",
            "required": false,
            "schema": {
              "description": "Header value to match with `header_name`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "min_size_bytes",
            "required": false,
            "schema": {
              "description": "Minimum message size in bytes.",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "max_size_bytes",
            "required": false,
            "schema": {
              "description": "Maximum message size in bytes.",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "keyword",
            "required": false,
            "schema": {
              "description": "Require this message keyword, such as `$seen`.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "not_keyword",
            "required": false,
            "schema": {
              "description": "Exclude messages with this keyword.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "description": "Filter to messages after this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "description": "Filter to messages before this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "has_attachment",
            "required": false,
            "schema": {
              "description": "When true, only return messages with attachments.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "is_unread",
            "required": false,
            "schema": {
              "description": "When true, only return unread messages.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "description": "Search text used to generate snippets.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "message_ids",
            "required": false,
            "schema": {
              "description": "Comma-separated message IDs, maximum 100.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100).",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxSearchSnippetsResultResponse"
                }
              }
            },
            "description": "Search snippets"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get message search snippets",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/messages/send": {
      "post": {
        "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`.",
        "operationId": "mailboxSendMessage",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "description": "Client-chosen unique key to safely retry the request. Cached for 24h per (mailbox, endpoint, key). Different body with same key returns 409 idempotency_conflict.",
              "maxLength": 255,
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMailboxMessageBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxSendResultResponse"
                }
              }
            },
            "description": "Message queued"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Idempotency conflict"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Message validation failed"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox service unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Send a mailbox message",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/quotas": {
      "get": {
        "description": "Returns a cursor-paginated list of quota usage and limits for the authenticated mailbox.",
        "operationId": "mailboxListQuotas",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "scope",
            "required": false,
            "schema": {
              "enum": [
                "account",
                "domain",
                "global"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "resource_type",
            "required": false,
            "schema": {
              "enum": [
                "count",
                "octets"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_by",
            "required": false,
            "schema": {
              "enum": [
                "name",
                "used"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_direction",
            "required": false,
            "schema": {
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxQuotaCursorListResponse"
                }
              }
            },
            "description": "Quota list"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mailbox quotas",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/quotas/changes": {
      "get": {
        "description": "Returns quota changes since a prior quota state, or the current quota state when omitted.",
        "operationId": "mailboxGetQuotaChanges",
        "parameters": [
          {
            "in": "query",
            "name": "since_state",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 500,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxChangesResponse"
                }
              }
            },
            "description": "Quota changes"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid sync state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get quota changes",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/session": {
      "get": {
        "description": "Returns mailbox API capabilities, resource state tokens, limits, and disabled feature flags for the authenticated mailbox.",
        "operationId": "mailboxGetSession",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxSessionResponse"
                }
              }
            },
            "description": "Mailbox API session"
          },
          "304": {
            "description": "Not modified"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox API key required"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox service unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get mailbox API session",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/submissions": {
      "get": {
        "description": "Returns a cursor-paginated list of send submissions for the authenticated mailbox, including delivery lifecycle fields when available.",
        "operationId": "mailboxListSubmissions",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "identity_ids",
            "required": false,
            "schema": {
              "description": "Comma-separated identity IDs, maximum 100.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "email_ids",
            "required": false,
            "schema": {
              "description": "Comma-separated message IDs, maximum 100.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "thread_ids",
            "required": false,
            "schema": {
              "description": "Comma-separated thread IDs, maximum 100.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "undo_status",
            "required": false,
            "schema": {
              "enum": [
                "pending",
                "final",
                "canceled"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_by",
            "required": false,
            "schema": {
              "enum": [
                "send_at",
                "email_id",
                "thread_id"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_direction",
            "required": false,
            "schema": {
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxSubmissionCursorListResponse"
                }
              }
            },
            "description": "Submission list"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mailbox submissions",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/submissions/{submission_id}": {
      "get": {
        "description": "Returns one send submission for the authenticated mailbox. Responses include a weak `ETag` header.",
        "operationId": "mailboxGetSubmission",
        "parameters": [
          {
            "in": "path",
            "name": "submission_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxSubmissionResponse"
                }
              }
            },
            "description": "Submission"
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Submission not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a mailbox submission",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/submissions/changes": {
      "get": {
        "description": "Returns send submission changes since a prior submission state, or the current state when omitted.",
        "operationId": "mailboxGetSubmissionChanges",
        "parameters": [
          {
            "in": "query",
            "name": "since_state",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 500,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxChangesResponse"
                }
              }
            },
            "description": "Submission changes"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid sync state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get submission changes",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/threads": {
      "get": {
        "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.",
        "operationId": "mailboxListThreads",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100).",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "description": "Full-text search query across thread messages.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "participant",
            "required": false,
            "schema": {
              "description": "Filter by participant email address or display name.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "folder_id",
            "required": false,
            "schema": {
              "description": "Filter to threads with messages in this folder ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "description": "Filter to threads updated after this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "description": "Filter to threads updated before this ISO 8601 timestamp.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "has_attachment",
            "required": false,
            "schema": {
              "description": "When true, only return threads with attachments.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "is_unread",
            "required": false,
            "schema": {
              "description": "When true, only return threads with unread messages.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "sort_direction",
            "required": false,
            "schema": {
              "description": "Sort direction.",
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxThreadSummaryCursorListResponse"
                }
              }
            },
            "description": "Thread list"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox API key required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mailbox threads",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/threads/{thread_id}": {
      "get": {
        "description": "Returns thread metadata, message IDs, participants, last message, unread count, and state for one conversation. Responses include a weak `ETag` header.",
        "operationId": "mailboxGetThread",
        "parameters": [
          {
            "in": "path",
            "name": "thread_id",
            "required": true,
            "schema": {
              "description": "Thread ID.",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxThreadDetailResponse"
                }
              }
            },
            "description": "Thread"
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Thread not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a mailbox thread",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/threads/{thread_id}/content": {
      "get": {
        "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.",
        "operationId": "mailboxGetThreadContent",
        "parameters": [
          {
            "in": "path",
            "name": "thread_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "part",
            "required": false,
            "schema": {
              "description": "Body part to return. `auto` prefers text when available.",
              "enum": [
                "auto",
                "text",
                "html"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "max_body_chars",
            "required": false,
            "schema": {
              "description": "Maximum body characters to return before truncation.",
              "maximum": 1000000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "strip_signature",
            "required": false,
            "schema": {
              "description": "When true, remove detected email signatures.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "strip_quotes",
            "required": false,
            "schema": {
              "description": "When true, remove quoted reply text.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_links",
            "required": false,
            "schema": {
              "description": "When true, include links extracted from the body.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_html",
            "required": false,
            "schema": {
              "description": "When true, include HTML content when available.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_headers",
            "required": false,
            "schema": {
              "description": "Header detail to include in the response.",
              "enum": [
                "none",
                "selected",
                "full"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include_attachments",
            "required": false,
            "schema": {
              "description": "Attachment detail to include. Contents are not returned.",
              "enum": [
                "none",
                "metadata"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxThreadContentResponse"
                }
              }
            },
            "description": "Clean thread content"
          },
          "304": {
            "description": "Not modified"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Thread not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get clean thread content",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/threads/{thread_id}/messages": {
      "get": {
        "description": "Returns cursor-paginated message summaries for one thread. Use the thread content endpoint when you need cleaned bodies.",
        "operationId": "mailboxListThreadMessages",
        "parameters": [
          {
            "in": "path",
            "name": "thread_id",
            "required": true,
            "schema": {
              "description": "Thread ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100).",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "description": "Message sort direction within the thread.",
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxMessageSummaryCursorListResponse"
                }
              }
            },
            "description": "Thread messages"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Thread not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List thread messages",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailbox/usage": {
      "get": {
        "description": "Returns a compact usage view derived from mailbox quota records. Responses include a weak `ETag` header.",
        "operationId": "mailboxListUsage",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.",
            "in": "query",
            "name": "mailbox_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxUsageResponse"
                }
              }
            },
            "description": "Mailbox usage"
          },
          "304": {
            "description": "Not modified"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get mailbox usage",
        "tags": [
          "Mailbox API"
        ]
      }
    },
    "/mailboxes": {
      "get": {
        "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.",
        "operationId": "managementListMailboxes",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Max results (default 50, max 100)",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "include_deleted",
            "required": false,
            "schema": {
              "description": "Set to `true` to include deleted mailboxes in the response. Default `false`. Deleted mailboxes are retained for audit and delivery history.",
              "enum": [
                "true"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxItemCursorListResponse"
                }
              }
            },
            "description": "Mailbox list"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mailboxes",
        "tags": [
          "Mailboxes"
        ]
      },
      "post": {
        "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`.",
        "operationId": "managementCreateMailbox",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "display_name": {
                    "description": "Optional display name shown in outbound From headers.",
                    "maxLength": 254,
                    "minLength": 1,
                    "type": "string"
                  },
                  "email": {
                    "description": "Mailbox email address to create.",
                    "maxLength": 254,
                    "minLength": 5,
                    "type": "string"
                  },
                  "quota_bytes": {
                    "description": "Storage quota in bytes. Allowed values: 1073741824 (1 GB), 5368709120 (5 GB), 53687091200 (50 GB).",
                    "example": 5368709120,
                    "minimum": 1,
                    "type": "integer"
                  },
                  "send_scope": {
                    "additionalProperties": false,
                    "description": "Optional outbound routing restrictions.",
                    "properties": {
                      "group_public_ids": {
                        "description": "Delivery group public IDs allowed for sending when type is `group`.",
                        "items": {
                          "maxLength": 128,
                          "minLength": 1,
                          "type": "string"
                        },
                        "type": "array"
                      },
                      "provider_public_ids": {
                        "description": "Provider public IDs allowed for sending when type is `providers`.",
                        "items": {
                          "maxLength": 128,
                          "minLength": 1,
                          "type": "string"
                        },
                        "type": "array"
                      },
                      "type": {
                        "description": "Outbound routing strategy. Use `providers` with provider_public_ids, or `group` with group_public_ids.",
                        "enum": [
                          "all",
                          "providers",
                          "group"
                        ],
                        "type": "string"
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "type": "object"
                  }
                },
                "required": [
                  "email"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxCreateResultResponse"
                }
              }
            },
            "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": {
                  "example": "/api/v1/mailboxes/mx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Email already in use (error code `conflict`), or `Idempotency-Key` was replayed with a different body (`idempotency_conflict`)."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Domain not yet verified or semantic validation failure"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Team is not yet provisioned for sending"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a mailbox",
        "tags": [
          "Mailboxes"
        ]
      }
    },
    "/mailboxes/{public_id}": {
      "delete": {
        "description": "Removes a mailbox from our mail platform, Amazon SES (for `@myagent.mx` addresses), and Sendmux. All associated API keys are revoked.",
        "operationId": "managementDeleteMailbox",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxDeletedResponse"
                }
              }
            },
            "description": "Deletion result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a mailbox",
        "tags": [
          "Mailboxes"
        ]
      },
      "get": {
        "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.",
        "operationId": "managementGetMailbox",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxItemResponse"
                }
              }
            },
            "description": "Mailbox",
            "headers": {
              "ETag": {
                "description": "Weak ETag for conditional GETs and optimistic-concurrency PATCHes.",
                "schema": {
                  "example": "W/\"a1b2c3d4e5f60718\"",
                  "type": "string"
                }
              }
            }
          },
          "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": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a mailbox",
        "tags": [
          "Mailboxes"
        ]
      },
      "patch": {
        "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.",
        "operationId": "managementUpdateMailbox",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs.",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateMailboxBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxItemResponse"
                }
              }
            },
            "description": "Updated mailbox",
            "headers": {
              "ETag": {
                "description": "Weak ETag for the post-update resource.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "`If-Match` ETag does not match the server's current version."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error — unsupported quota tier, quota below current usage, or cross-tenant send_scope reference"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a mailbox",
        "tags": [
          "Mailboxes"
        ]
      }
    },
    "/mailboxes/{public_id}/filters": {
      "get": {
        "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.",
        "operationId": "managementGetMailboxFilters",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilterStateResponse"
                }
              }
            },
            "description": "Filter state",
            "headers": {
              "ETag": {
                "description": "Weak ETag for conditional GETs and optimistic-concurrency PUTs.",
                "schema": {
                  "example": "W/\"a1b2c3d4e5f60718\"",
                  "type": "string"
                }
              }
            }
          },
          "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": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Filter service temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get mailbox sender filters",
        "tags": [
          "Mailbox Filters"
        ]
      },
      "put": {
        "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.",
        "operationId": "managementSetMailboxFilters",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs.",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetFilterStateBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilterStateResponse"
                }
              }
            },
            "description": "Updated filter state",
            "headers": {
              "ETag": {
                "description": "Weak ETag for the post-update resource.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "`If-Match` ETag does not match the server's current version."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Rule cap exceeded or invalid rule pattern"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Filter service temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace mailbox sender filters",
        "tags": [
          "Mailbox Filters"
        ]
      }
    },
    "/mailboxes/{public_id}/keys": {
      "post": {
        "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`.",
        "operationId": "managementCreateMailboxKey",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "app_name": {
                    "description": "Human-friendly label for the new API key.",
                    "maxLength": 255,
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "app_name"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxAppPasswordResultResponse"
                }
              }
            },
            "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": {
                  "example": "/api/v1/mailboxes/mx_clxxxxxxxxxxxxxxxxxxxxxxxxx/keys/smx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Credential limit reached (`limit_exceeded`) or idempotency key conflict (`idempotency_conflict`)."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox is not active"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Credential setup temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a mailbox API key",
        "tags": [
          "Mailboxes"
        ]
      }
    },
    "/mailboxes/{public_id}/keys/{key_id}": {
      "delete": {
        "description": "Revokes a specific bearer token + matching mailbox password. Idempotent on already-revoked keys.",
        "operationId": "managementDeleteMailboxKey",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "key_id",
            "required": true,
            "schema": {
              "description": "API key public ID",
              "example": "smx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxKeyDeletedResponse"
                }
              }
            },
            "description": "Deletion result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox or key not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a mailbox API key",
        "tags": [
          "Mailboxes"
        ]
      }
    },
    "/mailboxes/{public_id}/resume": {
      "post": {
        "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.",
        "operationId": "managementResumeMailbox",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "description": "Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key).",
              "example": "mailbox-resume-20260424-001",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxItemResponse"
                }
              }
            },
            "description": "Resumed mailbox"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Root API key required"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox is deleted, or `Idempotency-Key` was replayed with a different request body."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox service temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Resume a mailbox",
        "tags": [
          "Mailboxes"
        ]
      }
    },
    "/mailboxes/{public_id}/suspend": {
      "post": {
        "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.",
        "operationId": "managementSuspendMailbox",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Mailbox public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "description": "Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key).",
              "example": "mailbox-suspend-20260424-001",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxItemResponse"
                }
              }
            },
            "description": "Suspended mailbox"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Root API key required"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox is deleted, or `Idempotency-Key` was replayed with a different request body."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Mailbox service temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Suspend a mailbox",
        "tags": [
          "Mailboxes"
        ]
      }
    },
    "/mailboxes/availability": {
      "get": {
        "description": "Checks whether an email address can be reserved for mailbox creation. `@myagent.mx` availability is global across all teams; custom-domain availability is scoped to the caller's team and requires a verified send/receive mailbox domain.",
        "operationId": "managementCheckMailboxAvailability",
        "parameters": [
          {
            "in": "query",
            "name": "email",
            "required": true,
            "schema": {
              "description": "Email address to check.",
              "example": "agent@myagent.mx",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxAvailabilityResponse"
                }
              }
            },
            "description": "Mailbox address availability"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Root API key with mailbox.admin.create is required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check mailbox address availability",
        "tags": [
          "Mailboxes"
        ]
      }
    },
    "/providers": {
      "get": {
        "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`.",
        "operationId": "managementListProviders",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "active",
                "inactive",
                "error",
                "pending"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "enum": [
                "smtp",
                "gmail_api",
                "outlook_api",
                "amazon_ses"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100)",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderItemCursorListResponse"
                }
              }
            },
            "description": "Sending account list"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List sending accounts",
        "tags": [
          "Sending accounts"
        ]
      },
      "post": {
        "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.",
        "operationId": "managementCreateProvider",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProviderCreateBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderItemResponse"
                }
              }
            },
            "description": "Sending account created",
            "headers": {
              "Location": {
                "description": "Canonical GET URL for the new sending account.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Limit reached or idempotency conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create an SMTP sending account",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/{public_id}": {
      "delete": {
        "description": "Deletes a custom or connected sending account. The shared Amazon SES account cannot be deleted.",
        "operationId": "managementDeleteProvider",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Sending account public ID",
              "example": "dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderDeletedResponse"
                }
              }
            },
            "description": "Deletion result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Sending account not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Shared account cannot be deleted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a sending account",
        "tags": [
          "Sending accounts"
        ]
      },
      "get": {
        "description": "Returns one sending account. Responses include an ETag for conditional GET and optimistic PATCH.",
        "operationId": "managementGetProvider",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Sending account public ID",
              "example": "dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderItemResponse"
                }
              }
            },
            "description": "Sending account",
            "headers": {
              "ETag": {
                "description": "Weak ETag.",
                "schema": {
                  "example": "W/\"a1b2c3d4e5f60718\"",
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "Not Modified"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Sending account not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a sending account",
        "tags": [
          "Sending accounts"
        ]
      },
      "patch": {
        "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.",
        "operationId": "managementUpdateProvider",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Sending account public ID",
              "example": "dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs.",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProviderUpdateBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderItemResponse"
                }
              }
            },
            "description": "Updated sending account"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Sending account not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "ETag conflict"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Shared-account lock or unsupported field"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a sending account",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/{public_id}/activate": {
      "post": {
        "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.",
        "operationId": "managementActivateProvider",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Sending account public ID",
              "example": "dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderItemResponse"
                }
              }
            },
            "description": "Updated sending account"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Sending account not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Idempotency conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Activate a sending account",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/{public_id}/deactivate": {
      "post": {
        "description": "Disables a sending account. The shared Amazon SES account can be deactivated.",
        "operationId": "managementDeactivateProvider",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Sending account public ID",
              "example": "dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderItemResponse"
                }
              }
            },
            "description": "Updated sending account"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Sending account not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Idempotency conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Deactivate a sending account",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/{public_id}/test": {
      "post": {
        "description": "Runs a connection test for a custom SMTP account. The shared Amazon SES account and OAuth accounts cannot be tested through this endpoint.",
        "operationId": "managementTestProvider",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Sending account public ID",
              "example": "dprov_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderTestResultResponse"
                }
              }
            },
            "description": "Connection test result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Sending account not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Account cannot be tested"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Connection testing unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Test an SMTP sending account",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/limits": {
      "get": {
        "description": "Returns custom-account capacity and shared Amazon SES daily sending limit state.",
        "operationId": "managementGetProviderLimits",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderLimitsResponse"
                }
              }
            },
            "description": "Limit state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get sending account limits",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/limits/sending-accounts/request-increase": {
      "post": {
        "description": "Creates a request to increase the number of custom or connected sending accounts allowed for the team.",
        "operationId": "managementRequestSendingAccountLimitIncrease",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendingAccountLimitRequestResponse"
                }
              }
            },
            "description": "Request submitted"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "A request is already pending"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Increase request is not available yet"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request a sending account limit increase",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/shared-amazon-ses-limit-request": {
      "get": {
        "description": "Returns the shared Amazon SES daily limit state and any pending increase request.",
        "operationId": "managementGetSharedAmazonSesLimitRequest",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SharedAmazonSesLimitRequestPageResponse"
                }
              }
            },
            "description": "Shared Amazon SES limit request state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get shared Amazon SES limit request state",
        "tags": [
          "Sending accounts"
        ]
      },
      "post": {
        "description": "Creates a review request for the shared Amazon SES daily sending limit. This does not modify the limit directly.",
        "operationId": "managementCreateSharedAmazonSesLimitRequest",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SharedAmazonSesLimitRequestCreateResponse"
                }
              }
            },
            "description": "Request submitted"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Shared Amazon SES account not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "A request is already pending"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Increase request is not available yet"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request a shared Amazon SES daily limit increase",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/shared-amazon-ses-limit-request/{request_id}": {
      "delete": {
        "description": "Cancels a pending shared Amazon SES daily limit increase request for the caller's team. Approved or denied requests cannot be cancelled.",
        "operationId": "managementCancelSharedAmazonSesLimitRequest",
        "parameters": [
          {
            "in": "path",
            "name": "request_id",
            "required": true,
            "schema": {
              "description": "Shared Amazon SES limit request public ID",
              "example": "slir_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SharedAmazonSesLimitRequestCancelResponse"
                }
              }
            },
            "description": "Request cancelled"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Request not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Request has already been approved or denied"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Cancel a shared Amazon SES daily limit request",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/stats": {
      "get": {
        "description": "Returns aggregate counts of configured sending accounts with breakdowns by type and status.",
        "operationId": "managementGetProviderStats",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderStatsResponse"
                }
              }
            },
            "description": "Sending account statistics"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get sending account statistics",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/providers/usage": {
      "get": {
        "description": "Returns per-account delivery-log counts for today and the trailing 7-day window.",
        "operationId": "managementGetProviderUsage",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderUsageResponse"
                }
              }
            },
            "description": "Usage summary"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get sending account usage",
        "tags": [
          "Sending accounts"
        ]
      }
    },
    "/webhooks": {
      "get": {
        "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.",
        "operationId": "managementListWebhooks",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 50, max 100)",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSubscriptionCursorListResponse"
                }
              }
            },
            "description": "Subscription list"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List webhook subscriptions",
        "tags": [
          "Webhooks"
        ]
      },
      "post": {
        "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`.",
        "operationId": "managementCreateWebhook",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCreateBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSubscriptionWithSecretResponse"
                }
              }
            },
            "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": {
                  "example": "/api/v1/webhooks/whk_clxxxxxxxxxxxxxxxxxxxxxxxxx",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "`Idempotency-Key` was replayed with a different body (`idempotency_conflict`)."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation failed (e.g. non-https URL, unknown event type)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a webhook subscription",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/webhooks/{public_id}": {
      "delete": {
        "description": "Permanently removes the subscription. In-flight retries are dropped.",
        "operationId": "managementDeleteWebhook",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Webhook public ID",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeletedResponse"
                }
              }
            },
            "description": "Deletion result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Subscription not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a webhook subscription",
        "tags": [
          "Webhooks"
        ]
      },
      "get": {
        "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.",
        "operationId": "managementGetWebhook",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Webhook public ID",
              "example": "whk_clxxxxxxxxxxxxxxxxxxxxxxxxx",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a previous response. Returns 304 when unchanged.",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSubscriptionResponse"
                }
              }
            },
            "description": "Subscription",
            "headers": {
              "ETag": {
                "description": "Weak ETag for conditional GETs and optimistic-concurrency PATCHes.",
                "schema": {
                  "example": "W/\"a1b2c3d4e5f60718\"",
                  "type": "string"
                }
              }
            }
          },
          "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": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Subscription not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a webhook subscription",
        "tags": [
          "Webhooks"
        ]
      },
      "patch": {
        "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.",
        "operationId": "managementUpdateWebhook",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Webhook public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "description": "Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs.",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookUpdateBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSubscriptionResponse"
                }
              }
            },
            "description": "Updated subscription",
            "headers": {
              "ETag": {
                "description": "Weak ETag for the post-update resource.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Subscription not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "`If-Match` ETag does not match the server's current version."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation failed (e.g. non-https URL, unknown event type, empty event list)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a webhook subscription",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/webhooks/{public_id}/deliveries": {
      "get": {
        "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.",
        "operationId": "managementListDelivery",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Webhook public ID",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "description": "Pagination cursor — the `next_cursor` from the previous response.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Maximum results (default 25, max 100)",
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "event_type",
            "required": false,
            "schema": {
              "description": "Filter by event type.",
              "enum": [
                "message.delivered",
                "message.bounced",
                "message.complained",
                "message.rejected",
                "message.delivery_delayed",
                "message.received",
                "message.received.spam",
                "sendmux.test"
              ],
              "example": "message.bounced",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "result",
            "required": false,
            "schema": {
              "description": "Filter by delivery result.",
              "enum": [
                "success",
                "retrying",
                "failed",
                "permanent_failure"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryAttemptCursorListResponse"
                }
              }
            },
            "description": "Delivery-attempt list"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Invalid query parameter"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Subscription not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List webhook delivery attempts",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/webhooks/{public_id}/deliveries/{delivery_id}/payload": {
      "get": {
        "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`.",
        "operationId": "managementGetDeliveryPayload",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Webhook public ID",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "delivery_id",
            "required": true,
            "schema": {
              "description": "Delivery-attempt public ID",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryPayloadResponse"
                }
              }
            },
            "description": "Delivery payload"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Insufficient permissions"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Delivery not found or payload no longer available"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a webhook delivery payload",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/webhooks/{public_id}/rotate-secret": {
      "post": {
        "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`.",
        "operationId": "managementRotateWebhookSecret",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Webhook public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSubscriptionWithSecretResponse"
                }
              }
            },
            "description": "Subscription with new signing secret"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Subscription not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "`Idempotency-Key` was replayed against a different webhook (`idempotency_conflict`)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Rotate the signing secret",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/webhooks/{public_id}/test": {
      "post": {
        "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.",
        "operationId": "managementTestWebhook",
        "parameters": [
          {
            "in": "path",
            "name": "public_id",
            "required": true,
            "schema": {
              "description": "Webhook public ID",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "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",
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/WebhookTestResponse"
                        },
                        "meta": {
                          "$ref": "#/components/schemas/ResponseMeta"
                        }
                      },
                      "required": [
                        "data"
                      ],
                      "type": "object"
                    }
                  ],
                  "unevaluatedProperties": false
                }
              }
            },
            "description": "Test event published"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Subscription not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "`Idempotency-Key` was replayed against a different webhook (`idempotency_conflict`) or the webhook is not subscribed to `sendmux.test` (`conflict`)."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Event publish service is unavailable."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Send a synthetic test event",
        "tags": [
          "Webhooks"
        ]
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "servers": [
    {
      "description": "API v1",
      "url": "https://app.sendmux.ai/api/v1"
    }
  ],
  "webhooks": {}
}