components:
    headers:
        XRateLimitLimit:
            description: Public API request limit for the active window, when rate-limit enforcement succeeded.
            schema:
                minimum: 0
                type: integer
        XRateLimitRemaining:
            description: Remaining Public API requests in the active window, when rate-limit enforcement succeeded.
            schema:
                minimum: 0
                type: integer
        XRateLimitReset:
            description: Unix timestamp when the active Public API rate-limit window resets, when rate-limit enforcement succeeded.
            schema:
                minimum: 0
                type: integer
    parameters:
        ApiKeyId:
            in: path
            name: api_key_id
            required: true
            schema:
                type: string
        DomainId:
            in: path
            name: domain_id
            required: true
            schema:
                type: string
        EmailId:
            in: path
            name: email_id
            required: true
            schema:
                type: string
        IdempotencyKey:
            description: Recommended for retry-safe mutation requests. If omitted, the service generates and forwards a one-request idempotency key and returns it in the response headers.
            in: header
            name: Idempotency-Key
            required: false
            schema:
                maxLength: 255
                minLength: 8
                type: string
        Limit:
            in: query
            name: limit
            schema:
                default: 100
                maximum: 500
                minimum: 1
                type: integer
        PageToken:
            description: Opaque pagination cursor.
            in: query
            name: page_token
            schema:
                type: string
        QueryExecutionId:
            in: path
            name: query_execution_id
            required: true
            schema:
                type: string
        ReportArtifactId:
            in: path
            name: report_artifact_id
            required: true
            schema:
                type: string
        RequiredIdempotencyKey:
            description: Required client-generated idempotency key for send-creating requests. Reuse the same key when retrying the same request after a timeout or lost response.
            in: header
            name: Idempotency-Key
            required: true
            schema:
                maxLength: 255
                minLength: 8
                type: string
        ScheduleId:
            in: path
            name: schedule_id
            required: true
            schema:
                type: string
        SendId:
            in: path
            name: send_id
            required: true
            schema:
                type: string
        SenderId:
            in: path
            name: sender_id
            required: true
            schema:
                type: string
        WebhookEndpointId:
            in: path
            name: webhook_endpoint_id
            required: true
            schema:
                type: string
        WebhookEventId:
            in: path
            name: event_id
            required: true
            schema:
                type: string
        WorkspaceId:
            in: path
            name: workspace_id
            required: true
            schema:
                type: string
    responses:
        Error:
            content:
                application/json:
                    examples:
                        rate_limited:
                            summary: Public API rate limit exceeded.
                            value:
                                error:
                                    code: rate_limited
                                    details:
                                        rate_limit_class: public_send_write
                                        retry_after_seconds: 1
                                    message: The request exceeded the public API rate limit. Retry later.
                                    request_id: req_123
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
            description: Error response.
            headers:
                Retry-After:
                    description: Seconds to wait before retrying, when the error is rate-limit related and the value is known.
                    schema:
                        minimum: 0
                        type: integer
                X-RateLimit-Limit:
                    description: Request limit for the active window, when known.
                    schema:
                        minimum: 0
                        type: integer
                X-RateLimit-Remaining:
                    description: Remaining requests in the active window, when known.
                    schema:
                        minimum: 0
                        type: integer
                X-RateLimit-Reset:
                    description: Unix timestamp when the active rate-limit window resets, when known.
                    schema:
                        minimum: 0
                        type: integer
    schemas:
        ApiKey:
            properties:
                api_key_id:
                    type: string
                created_at:
                    format: date-time
                    type: string
                last_used_at:
                    format: date-time
                    type: string
                masked_key:
                    type: string
                name:
                    type: string
                scopes:
                    items:
                        $ref: '#/components/schemas/ApiScopeName'
                    type: array
                status:
                    enum:
                        - active
                        - revoked
                    type: string
            required:
                - api_key_id
                - name
                - status
                - scopes
                - created_at
            type: object
        ApiScope:
            properties:
                display_name:
                    type: string
                openfga_actions:
                    description: OpenFGA actions that must still authorize matching requests.
                    items:
                        type: string
                    type: array
                required_entitlement:
                    type: string
                scope:
                    $ref: '#/components/schemas/ApiScopeName'
                    description: Customer-facing scope label granted to an API key.
                status:
                    enum:
                        - available
                        - add_on_required
                        - unavailable
                    type: string
            required:
                - scope
                - display_name
                - status
                - openfga_actions
            type: object
        ApiScopeName:
            enum:
                - platform:read
                - api_keys:read
                - api_keys:write
                - senders:read
                - senders:write
                - domains:read
                - domains:write
                - billing:read
                - billing:write
                - usage:read
                - webhooks:read
                - webhooks:write
                - sends:read
                - sends:write
                - reporting:read
            type: string
        AutoRechargeRule:
            properties:
                auto_recharge_rule_id:
                    type: string
                billing_account_id:
                    type: string
                cap_mode:
                    enum:
                        - hard_cap
                        - soft_cap
                        - unspecified
                    type: string
                created_at:
                    format: date-time
                    type: string
                currency:
                    type: string
                enabled:
                    type: boolean
                last_triggered_at:
                    format: date-time
                    type: string
                monthly_cap_micros:
                    description: Calendar-month automatic recharge spend cap in micros of the billing currency.
                    minimum: 0
                    type: integer
                send_trigger_enabled:
                    type: boolean
                threshold_email_units:
                    minimum: 0
                    type: integer
                threshold_trigger_enabled:
                    type: boolean
                top_up_amount_micros:
                    minimum: 0
                    type: integer
                updated_at:
                    format: date-time
                    type: string
            required:
                - enabled
                - cap_mode
                - threshold_trigger_enabled
                - send_trigger_enabled
                - threshold_email_units
                - top_up_amount_micros
                - monthly_cap_micros
                - currency
            type: object
        BillingAccount:
            properties:
                active_rate_card_id:
                    type: string
                auto_recharge_enabled:
                    type: boolean
                billing_account_id:
                    type: string
                billing_contact_email:
                    format: email
                    type: string
                cap_mode:
                    enum:
                        - hard_cap
                        - soft_cap
                        - unspecified
                    type: string
                created_at:
                    format: date-time
                    type: string
                currency:
                    type: string
                free_quota_remaining:
                    minimum: 0
                    type: integer
                free_quota_total:
                    minimum: 0
                    type: integer
                owner_organization_id:
                    type: string
                paid_balance_micros:
                    description: Amount in micros of the account currency.
                    type: integer
                stripe_customer_ref:
                    type: string
                updated_at:
                    format: date-time
                    type: string
            required:
                - billing_account_id
                - owner_organization_id
                - currency
                - free_quota_total
                - free_quota_remaining
                - paid_balance_micros
                - cap_mode
                - auto_recharge_enabled
            type: object
        BillingActions:
            properties:
                can_configure_auto_recharge:
                    type: boolean
                can_manage_payment_method:
                    type: boolean
                can_start_top_up:
                    type: boolean
            required:
                - can_start_top_up
                - can_manage_payment_method
                - can_configure_auto_recharge
            type: object
        BillingForecast:
            properties:
                emails_affordable_with_balance:
                    minimum: 0
                    type: integer
                free_units_remaining:
                    minimum: 0
                    type: integer
                guidance:
                    type: string
                paid_balance_micros:
                    minimum: 0
                    type: integer
                price_per_email_micros:
                    minimum: 0
                    type: integer
            required:
                - price_per_email_micros
                - emails_affordable_with_balance
                - free_units_remaining
                - paid_balance_micros
            type: object
        BillingFundingRequest:
            properties:
                actor_source:
                    type: string
                amount_micros:
                    type: integer
                billing_account_id:
                    type: string
                billing_funding_request_id:
                    type: string
                completed_at:
                    format: date-time
                    type: string
                created_at:
                    format: date-time
                    type: string
                currency:
                    type: string
                failure_code:
                    type: string
                failure_detail:
                    type: string
                hosted_session_ref:
                    type: string
                hosted_session_url:
                    format: uri
                    type: string
                provider_customer_ref:
                    type: string
                provider_document_ref:
                    type: string
                provider_document_url:
                    format: uri
                    type: string
                provider_family:
                    type: string
                provider_payment_ref:
                    type: string
                requested_at:
                    format: date-time
                    type: string
                source_kind:
                    type: string
                status:
                    type: string
                trigger_description:
                    type: string
                updated_at:
                    format: date-time
                    type: string
            required:
                - billing_funding_request_id
                - billing_account_id
                - source_kind
                - status
                - amount_micros
                - currency
            type: object
        BillingHistoryRow:
            properties:
                amount_micros:
                    type: integer
                billing_balance_ledger_entry_id:
                    type: string
                billing_funding_request_id:
                    type: string
                currency:
                    type: string
                description:
                    type: string
                event_type:
                    type: string
                occurred_at:
                    format: date-time
                    type: string
                provider_document_ref:
                    type: string
                provider_document_url:
                    format: uri
                    type: string
                row_id:
                    type: string
                status:
                    type: string
            required:
                - row_id
                - amount_micros
                - status
            type: object
        BillingInvoiceDocument:
            properties:
                billing_history_row:
                    $ref: '#/components/schemas/BillingHistoryRow'
                description:
                    type: string
                hosted_url:
                    format: uri
                    type: string
                invoice_id:
                    type: string
                issued_at:
                    format: date-time
                    type: string
                provider_ref:
                    type: string
                status:
                    type: string
            required:
                - invoice_id
                - status
            type: object
        BillingInvoicePage:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/BillingInvoiceDocument'
                    type: array
                next_page_token:
                    type: string
            required:
                - data
            type: object
        BillingPortalSessionRequest:
            properties:
                flow:
                    enum:
                        - payment_method
                        - manage
                    type: string
                return_url:
                    format: uri
                    type: string
            required:
                - return_url
            type: object
        BillingRateCard:
            properties:
                active:
                    type: boolean
                billing_rate_card_id:
                    type: string
                created_at:
                    format: date-time
                    type: string
                currency:
                    type: string
                effective_end_time:
                    format: date-time
                    type: string
                effective_start_time:
                    format: date-time
                    type: string
                meter_family:
                    type: string
                owner_organization_id:
                    type: string
                price_per_unit_micros:
                    minimum: 0
                    type: integer
                updated_at:
                    format: date-time
                    type: string
            required:
                - billing_rate_card_id
                - owner_organization_id
                - meter_family
                - currency
                - price_per_unit_micros
                - active
            type: object
        BillingSummary:
            properties:
                actions:
                    $ref: '#/components/schemas/BillingActions'
                auto_recharge:
                    $ref: '#/components/schemas/AutoRechargeRule'
                balance:
                    $ref: '#/components/schemas/PrepaidBalance'
                billing_account:
                    $ref: '#/components/schemas/BillingAccount'
                billing_history:
                    items:
                        $ref: '#/components/schemas/BillingHistoryRow'
                    type: array
                free_quota:
                    $ref: '#/components/schemas/FreeQuota'
                payment_method:
                    $ref: '#/components/schemas/PaymentMethodSummary'
                rate_card:
                    $ref: '#/components/schemas/BillingRateCard'
                send_readiness:
                    $ref: '#/components/schemas/SendReadiness'
            required:
                - billing_account
                - free_quota
                - balance
                - auto_recharge
                - payment_method
                - billing_history
                - send_readiness
                - actions
            type: object
        BootstrapContext:
            properties:
                billing_subscription:
                    $ref: '#/components/schemas/BillingSummary'
                capabilities:
                    items:
                        $ref: '#/components/schemas/Capability'
                    type: array
                entitlements:
                    items:
                        $ref: '#/components/schemas/Entitlement'
                    type: array
                principal:
                    $ref: '#/components/schemas/PrincipalContext'
                send_readiness:
                    $ref: '#/components/schemas/SendReadiness'
                workspace:
                    $ref: '#/components/schemas/Workspace'
            required:
                - principal
                - workspace
                - capabilities
                - entitlements
                - billing_subscription
                - send_readiness
            type: object
        Capability:
            properties:
                key:
                    type: string
                reason_code:
                    type: string
                required_scopes:
                    items:
                        $ref: '#/components/schemas/ApiScopeName'
                    type: array
                status:
                    enum:
                        - available
                        - unavailable
                        - add_on_required
                        - preview
                    type: string
            required:
                - key
                - status
            type: object
        CreateApiKeyRequest:
            properties:
                expires_at:
                    format: date-time
                    type: string
                name:
                    type: string
                scopes:
                    description: Requested scope labels; each granted scope must map to an OpenFGA permission.
                    items:
                        $ref: '#/components/schemas/ApiScopeName'
                    minItems: 1
                    type: array
            required:
                - name
                - scopes
            type: object
        CreateApiKeyResponse:
            properties:
                api_key:
                    $ref: '#/components/schemas/ApiKey'
                secret:
                    description: Full secret shown only once.
                    type: string
            required:
                - api_key
                - secret
            type: object
        CreateBillingTopUpSessionRequest:
            properties:
                amount_micros:
                    description: Funding amount in micros of the selected currency.
                    minimum: 1
                    type: integer
                cancel_url:
                    format: uri
                    type: string
                currency:
                    type: string
                success_url:
                    format: uri
                    type: string
            required:
                - amount_micros
                - success_url
                - cancel_url
            type: object
        CreateDomainRequest:
            properties:
                domain_name:
                    type: string
            required:
                - domain_name
            type: object
        CreateEmailBatchRequest:
            properties:
                emails:
                    description: Each item is one email object for usage accounting. Item-level `scheduled_at` overrides the batch timestamp; attachments are rejected.
                    items:
                        $ref: '#/components/schemas/CreateEmailRequest'
                    maxItems: 100
                    minItems: 1
                    type: array
                execution_class:
                    default: production
                    description: Applies to every item. Use `test` to force the configured platform no-reply/sandbox sender.
                    enum:
                        - production
                        - test
                    type: string
                scheduled_at:
                    description: Optional RFC3339 timestamp applied to every batch item unless that item has its own `scheduled_at`.
                    format: date-time
                    type: string
            required:
                - emails
            type: object
        CreateEmailRequest:
            properties:
                execution_class:
                    default: production
                    description: Use `test` to route through the configured platform no-reply/sandbox sender without requiring customer-domain verification. Omit for production sends.
                    enum:
                        - production
                        - test
                    type: string
                from:
                    description: Verified sender mailbox. Display-name form such as `Acme <sender@example.com>` is allowed, but control characters, header injection, and malformed mailbox syntax are rejected.
                    maxLength: 320
                    type: string
                headers:
                    additionalProperties:
                        type: string
                    description: Custom email headers. Routing/content/provider-owned headers such as To, Cc, Bcc, From, Subject, Content-*, and DKIM-* are reserved and rejected.
                    type: object
                html:
                    description: Caller-authored HTML, up to 512 KiB. Unsafe script/event-handler content and null bytes are rejected.
                    maxLength: 524288
                    type: string
                message_class:
                    default: transactional
                    description: Preview public email sending is intentionally gated to `transactional`; marketing, commercial, and operational message classes are not publicly available.
                    enum:
                        - transactional
                    type: string
                reply_to:
                    description: Optional reply-to mailbox or mailbox array. Each item must be a single mailbox.
                    oneOf:
                        - format: email
                          type: string
                        - items:
                            format: email
                            type: string
                          type: array
                scheduled_at:
                    description: RFC3339 timestamp for scheduled single-email sends. Omit for send-now.
                    format: date-time
                    type: string
                subject:
                    description: Subject line. Control characters, Unicode directional controls, and server-template expression markers are rejected.
                    maxLength: 255
                    type: string
                tags:
                    additionalProperties: true
                    type: object
                text:
                    description: Plain-text body, up to 256 KiB. If omitted for HTML email, the service derives a text fallback.
                    maxLength: 262144
                    type: string
                to:
                    description: Single recipient mailbox or an array of recipient mailboxes. Comma-delimited recipient strings are rejected; pass multiple recipients as an array.
                    oneOf:
                        - format: email
                          type: string
                        - items:
                            format: email
                            type: string
                          minItems: 1
                          type: array
            required:
                - from
                - to
                - subject
            type: object
        CreateReportQueryExecutionRequest:
            properties:
                dimensions:
                    description: Optional public-safe breakdown dimensions, such as `channel_family`.
                    items:
                        type: string
                    type: array
                execution_mode:
                    default: query
                    description: Use `export` to create a durable report artifact that can be read through the report artifact endpoint.
                    enum:
                        - query
                        - export
                    type: string
                filters:
                    additionalProperties: true
                    type: object
                metrics:
                    description: Optional metric keys to include, such as `open_rate_v1` or `click_rate_v1`.
                    items:
                        type: string
                    type: array
                output_format:
                    description: Artifact output format. Only valid when `execution_mode` is `export`; defaults to `json` for exports.
                    enum:
                        - json
                        - csv
                    type: string
                report_type:
                    description: Public report family to execute.
                    type: string
                row_limit:
                    description: Maximum number of rows to return for inline or completed query results.
                    maximum: 200
                    minimum: 1
                    type: integer
                time_range:
                    additionalProperties: true
                    type: object
            required:
                - report_type
            type: object
        CreateScheduleRequest:
            properties:
                audience:
                    additionalProperties: true
                    type: object
                message_id:
                    type: string
                scheduled_at:
                    format: date-time
                    type: string
                timezone:
                    type: string
            required:
                - message_id
                - audience
                - scheduled_at
            type: object
        CreateSendRequest:
            properties:
                audience:
                    additionalProperties: true
                    type: object
                confirmation_token:
                    type: string
                message_id:
                    type: string
            required:
                - message_id
                - audience
            type: object
        CreateSenderRequest:
            properties:
                display_name:
                    type: string
                email:
                    format: email
                    type: string
            required:
                - email
                - display_name
            type: object
        CreateWebhookEndpointRequest:
            properties:
                event_types:
                    items:
                        $ref: '#/components/schemas/WebhookEventType'
                    minItems: 1
                    type: array
                url:
                    format: uri
                    type: string
            required:
                - url
                - event_types
            type: object
        CreateWebhookEndpointResponse:
            properties:
                secret:
                    description: Full signing secret shown only once.
                    type: string
                webhook_endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
            required:
                - webhook_endpoint
                - secret
            type: object
        Domain:
            properties:
                blocklist_status:
                    enum:
                        - pending
                        - clear
                        - blocked
                    type: string
                created_at:
                    format: date-time
                    type: string
                degraded_at:
                    format: date-time
                    type: string
                dkim_status:
                    enum:
                        - pending
                        - ready
                        - blocked
                    type: string
                dmarc_status:
                    enum:
                        - pending
                        - ready
                        - blocked
                    type: string
                domain_id:
                    type: string
                domain_name:
                    type: string
                last_checked_at:
                    format: date-time
                    type: string
                last_failure_message:
                    type: string
                last_failure_reason_code:
                    type: string
                last_ready_at:
                    format: date-time
                    type: string
                organizational_domain:
                    type: string
                overall_readiness_state:
                    enum:
                        - pending_verification
                        - ready
                        - degraded
                        - blocked
                    type: string
                provider_detail:
                    additionalProperties: true
                    type: object
                provider_family:
                    type: string
                return_path_status:
                    enum:
                        - pending
                        - ready
                        - blocked
                    type: string
                sandbox_testing_domain:
                    type: boolean
                status:
                    enum:
                        - pending_verification
                        - verified
                        - failed
                    type: string
                updated_at:
                    format: date-time
                    type: string
                verification_records:
                    items:
                        $ref: '#/components/schemas/DomainVerificationRecord'
                    type: array
            required:
                - domain_id
                - domain_name
                - status
                - overall_readiness_state
                - dkim_status
                - return_path_status
                - dmarc_status
                - blocklist_status
            type: object
        DomainPage:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/Domain'
                    type: array
            required:
                - data
            type: object
        DomainVerificationRecord:
            properties:
                check_kind:
                    enum:
                        - dkim
                        - return_path_mx
                        - return_path_spf
                        - dmarc
                    type: string
                expected_value:
                    type: string
                host:
                    type: string
                observed_value:
                    type: string
                record_type:
                    type: string
                remediation_hint:
                    type: string
                required:
                    type: boolean
                status:
                    enum:
                        - pending
                        - ready
                        - blocked
                    type: string
            required:
                - check_kind
                - record_type
                - host
                - expected_value
                - status
                - required
            type: object
        EmailBatch:
            properties:
                batch_id:
                    type: string
                data:
                    items:
                        $ref: '#/components/schemas/EmailSend'
                    type: array
                status:
                    enum:
                        - accepted
                    type: string
            required:
                - batch_id
                - status
                - data
            type: object
        EmailRecipients:
            properties:
                to:
                    items:
                        format: email
                        type: string
                    type: array
            required:
                - to
            type: object
        EmailSend:
            properties:
                created_at:
                    format: date-time
                    type: string
                email_id:
                    type: string
                from:
                    type: string
                message_class:
                    enum:
                        - transactional
                    type: string
                message_id:
                    type: string
                recipients:
                    $ref: '#/components/schemas/EmailRecipients'
                schedule_id:
                    type: string
                scheduled_at:
                    format: date-time
                    type: string
                send_id:
                    type: string
                status:
                    description: Convenience facade status for the acceptance response. `accepted` means durably queued for processing, not provider handoff or final delivery. Use `send_id` with `/v1/sends/{send_id}` and `/v1/logs?send_id=...` to read the durable execution record and later `accepted`, `running`, `completed`, `failed`, `canceling`, or `canceled` lifecycle evidence.
                    enum:
                        - accepted
                        - scheduled
                    type: string
                subject:
                    type: string
                text_derived:
                    type: boolean
            required:
                - email_id
                - message_id
                - send_id
                - status
                - recipients
            type: object
        Entitlement:
            properties:
                key:
                    type: string
                recovery_options:
                    items:
                        $ref: '#/components/schemas/LimitRecoveryOption'
                    type: array
                status:
                    enum:
                        - available
                        - unavailable
                        - add_on_required
                        - exceeded
                    type: string
                usage_metric:
                    type: string
            required:
                - key
                - status
            type: object
        ErrorResponse:
            properties:
                error:
                    properties:
                        code:
                            type: string
                        details:
                            additionalProperties: true
                            type: object
                        message:
                            type: string
                        request_id:
                            type: string
                    required:
                        - code
                        - message
                        - request_id
                    type: object
            required:
                - error
            type: object
        FreeQuota:
            properties:
                cap_mode:
                    enum:
                        - hard_cap
                        - soft_cap
                        - unspecified
                    type: string
                exhausted:
                    type: boolean
                one_time:
                    type: boolean
                remaining:
                    minimum: 0
                    type: integer
                total:
                    minimum: 0
                    type: integer
                updated_at:
                    format: date-time
                    type: string
                used:
                    minimum: 0
                    type: integer
            required:
                - total
                - remaining
                - used
                - one_time
                - exhausted
                - cap_mode
            type: object
        HostedSession:
            properties:
                billing_account_id:
                    type: string
                expires_at:
                    format: date-time
                    type: string
                funding_request:
                    $ref: '#/components/schemas/BillingFundingRequest'
                funding_request_id:
                    type: string
                hosted_session_type:
                    type: string
                payment_method:
                    $ref: '#/components/schemas/PaymentMethodSummary'
                provider_customer:
                    type: string
                provider_family:
                    type: string
                session_id:
                    type: string
                url:
                    format: uri
                    type: string
            required:
                - session_id
                - url
            type: object
        LimitRecoveryOption:
            properties:
                action:
                    enum:
                        - top_up
                        - manage_payment_method
                        - review_auto_recharge
                        - add_payment_method
                    type: string
                label:
                    type: string
                url:
                    format: uri
                    type: string
            required:
                - action
                - label
            type: object
        PaymentMethodSummary:
            properties:
                brand:
                    type: string
                cardholder_name:
                    type: string
                exp_month:
                    maximum: 12
                    minimum: 1
                    type: integer
                exp_year:
                    minimum: 2000
                    type: integer
                last4:
                    type: string
                provider_ref:
                    type: string
                state:
                    type: string
                updated_at:
                    format: date-time
                    type: string
            required:
                - state
            type: object
        PrepaidBalance:
            properties:
                currency:
                    type: string
                emails_affordable_with_balance:
                    minimum: 0
                    type: integer
                paid_balance_micros:
                    description: Amount in micros of the account currency.
                    type: integer
                price_per_email_micros:
                    minimum: 0
                    type: integer
            required:
                - paid_balance_micros
                - currency
                - emails_affordable_with_balance
                - price_per_email_micros
            type: object
        PrepaidUsageLimit:
            properties:
                balance:
                    $ref: '#/components/schemas/PrepaidBalance'
                free_quota:
                    $ref: '#/components/schemas/FreeQuota'
                metric:
                    type: string
                projected_units:
                    minimum: 1
                    type: integer
                recovery_options:
                    items:
                        $ref: '#/components/schemas/LimitRecoveryOption'
                    type: array
                send_readiness:
                    $ref: '#/components/schemas/SendReadiness'
            required:
                - metric
                - projected_units
                - free_quota
                - balance
                - send_readiness
                - recovery_options
            type: object
        PrincipalContext:
            properties:
                display_name:
                    nullable: true
                    type: string
                email:
                    format: email
                    nullable: true
                    type: string
                organization_id:
                    type: string
                principal_id:
                    type: string
                scopes:
                    description: Customer-facing scope labels backed by OpenFGA action checks.
                    items:
                        $ref: '#/components/schemas/ApiScopeName'
                    type: array
                workspace_id:
                    type: string
            required:
                - principal_id
                - organization_id
                - workspace_id
            type: object
        ReportArtifact:
            properties:
                created_at:
                    format: date-time
                    type: string
                download_url:
                    format: uri
                    type:
                        - string
                        - "null"
                expires_at:
                    format: date-time
                    type: string
                report_artifact_id:
                    type: string
                status:
                    enum:
                        - available
                        - expired
                    type: string
            required:
                - report_artifact_id
                - status
                - created_at
            type: object
        ReportQueryExecution:
            properties:
                artifact_id:
                    type: string
                completed_at:
                    format: date-time
                    type: string
                created_at:
                    format: date-time
                    type: string
                failure_code:
                    description: Sanitized failure reason code when the execution fails.
                    type: string
                query_execution_id:
                    type: string
                result:
                    additionalProperties: true
                    description: Inline query result when the reporting execution has a completed public-safe result available.
                    type: object
                status:
                    enum:
                        - queued
                        - running
                        - completed
                        - failed
                        - canceled
                    type: string
            required:
                - query_execution_id
                - status
                - created_at
            type: object
        RotateWebhookSecretResponse:
            properties:
                secret:
                    description: Full signing secret shown only once.
                    type: string
                webhook_endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
            required:
                - webhook_endpoint
                - secret
            type: object
        Schedule:
            properties:
                audience:
                    additionalProperties: true
                    type: object
                created_at:
                    format: date-time
                    type: string
                message_id:
                    type: string
                schedule_id:
                    type: string
                scheduled_at:
                    format: date-time
                    type: string
                status:
                    enum:
                        - scheduled
                        - paused
                        - running
                        - completed
                        - failed
                        - canceled
                    type: string
            required:
                - schedule_id
                - message_id
                - status
                - scheduled_at
                - created_at
            type: object
        SchedulePage:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/Schedule'
                    type: array
                next_page_token:
                    type: string
            required:
                - data
            type: object
        Send:
            properties:
                audience:
                    additionalProperties: true
                    type: object
                completed_at:
                    format: date-time
                    type: string
                created_at:
                    format: date-time
                    type: string
                message_id:
                    type: string
                send_id:
                    type: string
                status:
                    $ref: '#/components/schemas/SendStatus'
            required:
                - send_id
                - message_id
                - status
                - created_at
            type: object
        SendEmailRequest:
            properties:
                execution_class:
                    default: production
                    description: Use `test` to route through the configured platform no-reply/sandbox sender. Omit for production sends.
                    enum:
                        - production
                        - test
                    type: string
                headers:
                    additionalProperties:
                        type: string
                    description: Custom email headers. Routing/content/provider-owned headers such as To, Cc, Bcc, From, Subject, Content-*, and DKIM-* are reserved and rejected.
                    type: object
                message_class:
                    default: transactional
                    description: Preview public email sending is intentionally gated to `transactional`; marketing, commercial, and operational message classes are not publicly available.
                    enum:
                        - transactional
                    type: string
                scheduled_at:
                    format: date-time
                    type: string
                tags:
                    additionalProperties: true
                    type: object
                to:
                    description: Single recipient mailbox or an array of recipient mailboxes. Comma-delimited recipient strings are rejected; pass multiple recipients as an array.
                    oneOf:
                        - format: email
                          type: string
                        - items:
                            format: email
                            type: string
                          minItems: 1
                          type: array
            required:
                - to
            type: object
        SendPage:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/Send'
                    type: array
                next_page_token:
                    type: string
            required:
                - data
            type: object
        SendReadiness:
            properties:
                auto_recharge_attempted:
                    type: boolean
                available_units:
                    minimum: 0
                    type: integer
                can_send_now:
                    type: boolean
                cap_mode:
                    enum:
                        - hard_cap
                        - soft_cap
                        - unspecified
                    type: string
                detail:
                    type: string
                free_units_remaining:
                    minimum: 0
                    type: integer
                paid_balance_remaining_micros:
                    minimum: 0
                    type: integer
                reason_code:
                    type: string
                state:
                    type: string
            required:
                - state
                - can_send_now
                - available_units
                - free_units_remaining
                - paid_balance_remaining_micros
                - cap_mode
                - auto_recharge_attempted
            type: object
        SendStatus:
            description: Execution-record status. Email facade responses initially return `accepted` or `scheduled`; use `send_id` with `/v1/sends/{send_id}` to follow the execution lifecycle.
            enum:
                - accepted
                - running
                - completed
                - failed
                - canceling
                - canceled
            type: string
        Sender:
            properties:
                checked_at:
                    format: date-time
                    type: string
                display_name:
                    type: string
                domain_id:
                    type: string
                email:
                    format: email
                    type: string
                production_authorized:
                    type: boolean
                readiness_state:
                    enum:
                        - not_configured
                        - pending_verification
                        - ready
                        - degraded
                        - blocked
                    type: string
                reason_code:
                    type: string
                recommended_actions:
                    items:
                        type: string
                    type: array
                remediation:
                    type: string
                sender_id:
                    type: string
                status:
                    enum:
                        - pending_verification
                        - verified
                        - disabled
                    type: string
                test_send_authorized:
                    type: boolean
            required:
                - sender_id
                - email
                - display_name
                - status
                - readiness_state
                - production_authorized
                - test_send_authorized
            type: object
        SenderPage:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/Sender'
                    type: array
            required:
                - data
            type: object
        UpdateApiKeyRequest:
            minProperties: 1
            properties:
                clear_expires_at:
                    type: boolean
                expires_at:
                    format: date-time
                    type: string
                name:
                    type: string
                scopes:
                    description: Replacement scope set; each granted scope must map to an OpenFGA permission.
                    items:
                        $ref: '#/components/schemas/ApiScopeName'
                    minItems: 1
                    type: array
            type: object
        UpdateSenderRequest:
            minProperties: 1
            properties:
                display_name:
                    type: string
                status:
                    enum:
                        - disabled
                    type: string
            type: object
        UpdateWebhookEndpointRequest:
            minProperties: 1
            properties:
                event_types:
                    items:
                        $ref: '#/components/schemas/WebhookEventType'
                    minItems: 1
                    type: array
                status:
                    enum:
                        - active
                        - disabled
                    type: string
                url:
                    format: uri
                    type: string
            type: object
        UsageFundingSummary:
            properties:
                auto_recharge:
                    $ref: '#/components/schemas/AutoRechargeRule'
                balance:
                    $ref: '#/components/schemas/PrepaidBalance'
                forecast:
                    $ref: '#/components/schemas/BillingForecast'
                free_quota:
                    $ref: '#/components/schemas/FreeQuota'
                payment_method:
                    $ref: '#/components/schemas/PaymentMethodSummary'
                rate_card:
                    $ref: '#/components/schemas/BillingRateCard'
                send_readiness:
                    $ref: '#/components/schemas/SendReadiness'
            required:
                - free_quota
                - balance
                - auto_recharge
                - payment_method
                - send_readiness
                - forecast
            type: object
        UsageLimitPage:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/PrepaidUsageLimit'
                    type: array
                next_page_token:
                    type: string
            required:
                - data
            type: object
        WebhookEndpoint:
            properties:
                event_types:
                    items:
                        $ref: '#/components/schemas/WebhookEventType'
                    type: array
                status:
                    enum:
                        - active
                        - disabled
                        - archived
                    type: string
                url:
                    format: uri
                    type: string
                webhook_endpoint_id:
                    type: string
            required:
                - webhook_endpoint_id
                - url
                - status
                - event_types
            type: object
        WebhookEvent:
            properties:
                created_at:
                    format: date-time
                    type: string
                delivery_attempts:
                    minimum: 0
                    type: integer
                event_id:
                    type: string
                event_type:
                    type: string
                last_attempt_at:
                    format: date-time
                    type: string
                status:
                    enum:
                        - pending
                        - delivered
                        - failed
                        - redelivery_requested
                    type: string
                webhook_endpoint_id:
                    type: string
            required:
                - event_id
                - event_type
                - status
                - created_at
            type: object
        WebhookEventPage:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/WebhookEvent'
                    type: array
                next_page_token:
                    type: string
            required:
                - data
            type: object
        WebhookEventType:
            description: Stable customer-webhook event kinds currently advertised by the preview API.
            enum:
                - email.sent
                - email.delivered
                - email.failed
                - email.bounced
                - email.complained
                - email.scheduled
                - email.canceled
                - domain.created
                - domain.updated
                - domain.deleted
                - artifact.generated
                - report.generated
                - insight.generated
                - recommendation.generated
            type: string
        Workspace:
            properties:
                display_name:
                    type: string
                organization_id:
                    type: string
                status:
                    enum:
                        - active
                        - suspended
                        - archived
                    type: string
                workspace_id:
                    type: string
            required:
                - workspace_id
                - organization_id
                - display_name
                - status
            type: object
    securitySchemes:
        ApiKeyAuth:
            description: 'Use `Authorization: Bearer <api_key>`.'
            scheme: bearer
            type: http
info:
    description: |
        This OpenAPI document is the design-time source of truth for the external REST API. REST is a sibling adapter over the same customer-facing runtime contracts used by Public MCP; it is not a JSON-RPC wrapper around MCP tools/call.
    license:
        name: Proprietary
        url: https://www.constantcontact.com/legal
    summary: Preview contract for the external REST API surface.
    title: Constant Contact AI-Native Public API
    version: 0.1.0-preview
openapi: 3.1.0
paths:
    /v1/api-keys:
        get:
            operationId: listApiKeys
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    data:
                                        items:
                                            $ref: '#/components/schemas/ApiKey'
                                        type: array
                                required:
                                    - data
                                type: object
                    description: API key list.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List API keys visible to the caller.
            tags:
                - API Keys
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - api_keys:read
        post:
            operationId: createApiKey
            parameters:
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateApiKeyRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateApiKeyResponse'
                    description: API key created. The full secret is returned only once.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Create a scoped API key.
            tags:
                - API Keys
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - api_keys:write
    /v1/api-keys/{api_key_id}:
        patch:
            operationId: updateApiKey
            parameters:
                - $ref: '#/components/parameters/ApiKeyId'
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateApiKeyRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ApiKey'
                    description: API key updated.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Update API key metadata or requested scopes.
            tags:
                - API Keys
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - api_keys:write
    /v1/api-keys/{api_key_id}:revoke:
        post:
            operationId: revokeApiKey
            parameters:
                - $ref: '#/components/parameters/ApiKeyId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ApiKey'
                    description: API key revoked.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Revoke an API key.
            tags:
                - API Keys
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - api_keys:write
    /v1/api-keys/{api_key_id}:rotate:
        post:
            description: The new full secret is returned only once; the previous secret is revoked after the configured overlap window.
            operationId: rotateApiKey
            parameters:
                - $ref: '#/components/parameters/ApiKeyId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateApiKeyResponse'
                    description: API key rotated.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Rotate an API key secret.
            tags:
                - API Keys
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - api_keys:write
    /v1/api-scopes:
        get:
            operationId: listApiScopes
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    data:
                                        items:
                                            $ref: '#/components/schemas/ApiScope'
                                        type: array
                                required:
                                    - data
                                type: object
                    description: API scope catalog.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List available API key scopes and their entitlement posture.
            tags:
                - API Keys
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - api_keys:read
    /v1/billing/invoices:
        get:
            operationId: listBillingInvoices
            parameters:
                - $ref: '#/components/parameters/Limit'
                - $ref: '#/components/parameters/PageToken'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BillingInvoicePage'
                    description: Provider document page.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List prepaid funding documents and provider receipts.
            tags:
                - Billing
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - billing:read
    /v1/billing/portal-sessions:
        post:
            operationId: createBillingPortalSession
            parameters:
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/BillingPortalSessionRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HostedSession'
                    description: Portal session.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Create a hosted billing portal session.
            tags:
                - Billing
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - billing:write
    /v1/billing/subscription:
        get:
            operationId: getBillingSubscription
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BillingSummary'
                    description: Prepaid billing summary.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read current prepaid billing-account posture.
            tags:
                - Billing
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - billing:read
    /v1/billing/top-up-sessions:
        post:
            operationId: createBillingTopUpSession
            parameters:
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateBillingTopUpSessionRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HostedSession'
                    description: Top-up session.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Create a hosted session to add prepaid balance.
            tags:
                - Billing
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - billing:write
    /v1/bootstrap:
        get:
            description: Consolidates the current principal, workspace, capabilities, entitlements, billing summary, and send readiness needed for initial client bootstrap.
            operationId: getBootstrap
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BootstrapContext'
                    description: Public API bootstrap context.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Return the startup context for SDKs and dashboards.
            tags:
                - Platform
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - platform:read
    /v1/capabilities:
        get:
            operationId: listCapabilities
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    capabilities:
                                        items:
                                            $ref: '#/components/schemas/Capability'
                                        type: array
                                required:
                                    - capabilities
                                type: object
                    description: Capability inventory.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List REST capability availability and entitlement posture.
            tags:
                - Platform
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - platform:read
    /v1/domains:
        get:
            operationId: listDomains
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DomainPage'
                    description: Domain page.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List sending domains.
            tags:
                - Senders
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - domains:read
        post:
            operationId: createDomain
            parameters:
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateDomainRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Domain'
                    description: Existing workspace domain returned for an idempotent create.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Domain'
                    description: Domain created.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Create a sending domain.
            tags:
                - Senders
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - domains:write
    /v1/domains/{domain_id}:
        get:
            operationId: getDomain
            parameters:
                - $ref: '#/components/parameters/DomainId'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Domain'
                    description: Domain.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read one sending domain.
            tags:
                - Senders
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - domains:read
    /v1/domains/{domain_id}:verify:
        post:
            operationId: verifyDomain
            parameters:
                - $ref: '#/components/parameters/DomainId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Domain'
                    description: Domain verification accepted.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Request or re-check sending domain verification.
            tags:
                - Senders
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - domains:write
    /v1/emails:
        post:
            description: |
                Convenience facade over Delivery intake. A `202` response means the request was authenticated, authorized, validated, and durably accepted for asynchronous processing. Sender readiness, authoring compilation, usage settlement, release handoff, rendering, and provider dispatch complete after the response and are visible through `/v1/sends/{send_id}` and logs. When `scheduled_at` is supplied, the asynchronous worker binds the accepted intake to Scheduling before release.
            operationId: createEmail
            parameters:
                - $ref: '#/components/parameters/RequiredIdempotencyKey'
            requestBody:
                content:
                    application/json:
                        examples:
                            scheduled:
                                value:
                                    from: sender@example.com
                                    html: <p>We will see you tomorrow.</p>
                                    scheduled_at: "2026-05-05T18:30:00Z"
                                    subject: Tomorrow's reminder
                                    to:
                                        - ada@example.com
                            send_now:
                                value:
                                    from: Acme <sender@example.com>
                                    html: <p>Your verification code is 123456.</p>
                                    subject: Your verification code
                                    to:
                                        - ada@example.com
                        schema:
                            $ref: '#/components/schemas/CreateEmailRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EmailSend'
                    description: Email send durably accepted for asynchronous processing.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Create and send a caller-authored HTML or text email.
            tags:
                - Emails
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - sends:write
    /v1/emails/{email_id}:send:
        post:
            operationId: sendEmail
            parameters:
                - $ref: '#/components/parameters/EmailId'
                - $ref: '#/components/parameters/RequiredIdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SendEmailRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EmailSend'
                    description: Email send accepted or scheduled.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Send or schedule an existing generated or caller-authored draft.
            tags:
                - Emails
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - sends:write
    /v1/emails/batch:
        post:
            description: Batch v1 validates all items before creating child sends, rejects attachments, supports send-now or scheduled delivery, and supports at most 100 emails.
            operationId: createEmailBatch
            parameters:
                - $ref: '#/components/parameters/RequiredIdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateEmailBatchRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EmailBatch'
                    description: Batch accepted.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Create sends for multiple distinct emails.
            tags:
                - Emails
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - sends:write
    /v1/entitlements:
        get:
            operationId: listEntitlements
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    data:
                                        items:
                                            $ref: '#/components/schemas/Entitlement'
                                        type: array
                                required:
                                    - data
                                type: object
                    description: Entitlement list.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List entitlement and add-on posture for the caller workspace.
            tags:
                - Platform
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - platform:read
    /v1/me:
        get:
            operationId: getCurrentPrincipal
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PrincipalContext'
                    description: Authenticated principal context.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Return the authenticated API principal and default workspace context.
            tags:
                - Platform
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - platform:read
    /v1/reports/artifacts/{report_artifact_id}:
        get:
            operationId: getReportArtifact
            parameters:
                - $ref: '#/components/parameters/ReportArtifactId'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ReportArtifact'
                    description: Report artifact.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read a generated report artifact or artifact download metadata.
            tags:
                - Reporting
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - reporting:read
    /v1/reports/query-executions:
        post:
            operationId: createReportQueryExecution
            parameters:
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        examples:
                            export:
                                summary: Artifact-producing report export
                                value:
                                    execution_mode: export
                                    output_format: csv
                                    report_type: summary
                                    time_range:
                                        preset: last_30_days
                            open_click_rates:
                                summary: Open and click rates by channel
                                value:
                                    dimensions:
                                        - channel_family
                                    metrics:
                                        - open_rate_v1
                                        - click_rate_v1
                                    report_type: delivery_metric_breakdown
                                    row_limit: 30
                                    time_range:
                                        preset: last_7_days
                            structured_query:
                                summary: Structured report query
                                value:
                                    report_type: summary
                                    time_range:
                                        preset: last_7_days
                        schema:
                            $ref: '#/components/schemas/CreateReportQueryExecutionRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ReportQueryExecution'
                    description: Report query accepted.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Start an async report query or export execution.
            tags:
                - Reporting
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - reporting:write
    /v1/reports/query-executions/{query_execution_id}:
        get:
            operationId: getReportQueryExecution
            parameters:
                - $ref: '#/components/parameters/QueryExecutionId'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ReportQueryExecution'
                    description: Report query execution.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read report query execution status.
            tags:
                - Reporting
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - reporting:read
    /v1/reports/results-summary:
        get:
            operationId: getResultsSummary
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties: true
                                type: object
                    description: Results summary.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read customer-safe results summary.
            tags:
                - Reporting
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - reporting:read
    /v1/schedules:
        get:
            operationId: listSchedules
            parameters:
                - $ref: '#/components/parameters/Limit'
                - $ref: '#/components/parameters/PageToken'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SchedulePage'
                    description: Schedule page.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List scheduled sends.
            tags:
                - Scheduling
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - schedules:read
        post:
            description: Scheduling must respect release gates, operator pause controls, usage controls, and delivery eligibility.
            operationId: createSchedule
            parameters:
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateScheduleRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Schedule'
                    description: Schedule accepted.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Schedule a send.
            tags:
                - Scheduling
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - schedules:write
    /v1/schedules/{schedule_id}:
        get:
            operationId: getSchedule
            parameters:
                - $ref: '#/components/parameters/ScheduleId'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Schedule'
                    description: Schedule.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read one schedule.
            tags:
                - Scheduling
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - schedules:read
    /v1/schedules/{schedule_id}:cancel:
        post:
            operationId: cancelSchedule
            parameters:
                - $ref: '#/components/parameters/ScheduleId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Schedule'
                    description: Schedule cancellation accepted.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Cancel a scheduled send.
            tags:
                - Scheduling
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - schedules:write
    /v1/schedules/{schedule_id}:pause:
        post:
            operationId: pauseSchedule
            parameters:
                - $ref: '#/components/parameters/ScheduleId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Schedule'
                    description: Schedule paused.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Pause a scheduled send.
            tags:
                - Scheduling
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - schedules:write
    /v1/schedules/{schedule_id}:resume:
        post:
            operationId: resumeSchedule
            parameters:
                - $ref: '#/components/parameters/ScheduleId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Schedule'
                    description: Schedule resumed.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Resume a paused schedule.
            tags:
                - Scheduling
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - schedules:write
    /v1/senders:
        get:
            operationId: listSenders
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SenderPage'
                    description: Sender page.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List sender identities.
            tags:
                - Senders
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - senders:read
        post:
            operationId: createSender
            parameters:
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateSenderRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Sender'
                    description: Sender created.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Create a sender identity.
            tags:
                - Senders
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - senders:write
    /v1/senders/{sender_id}:
        get:
            operationId: getSender
            parameters:
                - $ref: '#/components/parameters/SenderId'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Sender'
                    description: Sender.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read one sender identity.
            tags:
                - Senders
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - senders:read
        patch:
            operationId: updateSender
            parameters:
                - $ref: '#/components/parameters/SenderId'
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateSenderRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Sender'
                    description: Sender updated.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Update sender identity metadata.
            tags:
                - Senders
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - senders:write
    /v1/sends:
        get:
            operationId: listSends
            parameters:
                - $ref: '#/components/parameters/Limit'
                - $ref: '#/components/parameters/PageToken'
                - description: Filter by public send execution status.
                  in: query
                  name: status
                  schema:
                    $ref: '#/components/schemas/SendStatus'
                - description: Inclusive RFC3339 lower bound for send creation time.
                  in: query
                  name: created_at_from
                  schema:
                    format: date-time
                    type: string
                - description: Inclusive RFC3339 upper bound for send creation time.
                  in: query
                  name: created_at_to
                  schema:
                    format: date-time
                    type: string
                - description: Case-insensitive match against the send target or recipient summary.
                  in: query
                  name: recipient
                  schema:
                    type: string
                - description: Filter sends whose caller-provided tags include this key.
                  in: query
                  name: tag_key
                  schema:
                    type: string
                - description: Optional exact tag value match; requires `tag_key`.
                  in: query
                  name: tag_value
                  schema:
                    type: string
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SendPage'
                    description: Send page.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List send executions.
            tags:
                - Sends
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - sends:read
        post:
            description: Send execution must pass usage, preference, suppression, policy, and confirmation gates.
            operationId: createSend
            parameters:
                - $ref: '#/components/parameters/RequiredIdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateSendRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Send'
                    description: Send accepted.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Start an immediate send.
            tags:
                - Sends
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - sends:write
    /v1/sends/{send_id}:
        get:
            operationId: getSend
            parameters:
                - $ref: '#/components/parameters/SendId'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Send'
                    description: Send.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read one send execution.
            tags:
                - Sends
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - sends:read
    /v1/sends/{send_id}:cancel:
        post:
            operationId: cancelSend
            parameters:
                - $ref: '#/components/parameters/SendId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Send'
                    description: Send cancellation accepted.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Cancel a send where cancellation is still safe.
            tags:
                - Sends
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - sends:write
    /v1/usage:
        get:
            operationId: getUsageSummary
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UsageFundingSummary'
                    description: Prepaid usage funding summary.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read current prepaid funding posture for sending.
            tags:
                - Billing
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - usage:read
    /v1/usage/limits:
        get:
            description: Recovery options can include adding funds, managing payment methods, or reviewing auto-recharge.
            operationId: listUsageLimits
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UsageLimitPage'
                    description: Prepaid usage limit page.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List prepaid send-admission limits and recovery options.
            tags:
                - Billing
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - usage:read
    /v1/webhook-endpoints:
        get:
            operationId: listWebhookEndpoints
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    data:
                                        items:
                                            $ref: '#/components/schemas/WebhookEndpoint'
                                        type: array
                                required:
                                    - data
                                type: object
                    description: Webhook endpoint list.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List webhook endpoints.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:read
        post:
            operationId: createWebhookEndpoint
            parameters:
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateWebhookEndpointRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateWebhookEndpointResponse'
                    description: Webhook endpoint created.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Create a webhook endpoint.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:write
    /v1/webhook-endpoints/{webhook_endpoint_id}:
        delete:
            description: Delivery history, signatures, and audit evidence are preserved even when the endpoint is removed from active delivery.
            operationId: archiveWebhookEndpoint
            parameters:
                - $ref: '#/components/parameters/WebhookEndpointId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WebhookEndpoint'
                    description: Webhook endpoint archived.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Archive a webhook endpoint and stop future deliveries.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:write
        get:
            operationId: getWebhookEndpoint
            parameters:
                - $ref: '#/components/parameters/WebhookEndpointId'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WebhookEndpoint'
                    description: Webhook endpoint.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read one webhook endpoint.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:read
        patch:
            operationId: updateWebhookEndpoint
            parameters:
                - $ref: '#/components/parameters/WebhookEndpointId'
                - $ref: '#/components/parameters/IdempotencyKey'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateWebhookEndpointRequest'
                required: true
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WebhookEndpoint'
                    description: Webhook endpoint updated.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Update webhook endpoint URL, event types, or status.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:write
    /v1/webhook-endpoints/{webhook_endpoint_id}:disable:
        post:
            operationId: disableWebhookEndpoint
            parameters:
                - $ref: '#/components/parameters/WebhookEndpointId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WebhookEndpoint'
                    description: Webhook endpoint disabled.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Disable a webhook endpoint without deleting its configuration.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:write
    /v1/webhook-endpoints/{webhook_endpoint_id}:rotate-secret:
        post:
            description: The new signing secret is returned only once.
            operationId: rotateWebhookEndpointSecret
            parameters:
                - $ref: '#/components/parameters/WebhookEndpointId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RotateWebhookSecretResponse'
                    description: Webhook signing secret rotated.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Rotate a webhook endpoint signing secret.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:write
    /v1/webhook-events:
        get:
            operationId: listWebhookEvents
            parameters:
                - $ref: '#/components/parameters/Limit'
                - $ref: '#/components/parameters/PageToken'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WebhookEventPage'
                    description: Webhook event page.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List webhook delivery events.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:read
    /v1/webhook-events/{event_id}:redeliver:
        post:
            operationId: redeliverWebhookEvent
            parameters:
                - $ref: '#/components/parameters/WebhookEventId'
                - $ref: '#/components/parameters/IdempotencyKey'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WebhookEvent'
                    description: Webhook event redelivery accepted.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Request redelivery for a webhook event.
            tags:
                - Webhooks
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - webhooks:write
    /v1/workspaces:
        get:
            operationId: listWorkspaces
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    data:
                                        items:
                                            $ref: '#/components/schemas/Workspace'
                                        type: array
                                required:
                                    - data
                                type: object
                    description: Workspace list.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: List workspaces visible to the API principal.
            tags:
                - Platform
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - platform:read
    /v1/workspaces/{workspace_id}:
        get:
            operationId: getWorkspace
            parameters:
                - $ref: '#/components/parameters/WorkspaceId'
            responses:
                4XX:
                    $ref: '#/components/responses/Error'
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Workspace'
                    description: Workspace.
                    headers:
                        X-RateLimit-Limit:
                            $ref: '#/components/headers/XRateLimitLimit'
                        X-RateLimit-Remaining:
                            $ref: '#/components/headers/XRateLimitRemaining'
                        X-RateLimit-Reset:
                            $ref: '#/components/headers/XRateLimitReset'
                default:
                    $ref: '#/components/responses/Error'
            summary: Read one workspace.
            tags:
                - Platform
            x-ctct-implementation-status: preview
            x-ctct-required-api-key-scopes:
                - platform:read
security:
    - ApiKeyAuth: []
servers:
    - url: https://api.ctct.dev
tags:
    - description: Transactional-only caller-authored email creation, scheduling, and immediate batches.
      name: Emails
    - description: Transactional send status and delivery execution records.
      name: Sends
    - description: Scheduled delivery creation, pause, resume, and cancellation.
      name: Scheduling
    - description: Sender identities and sending domain setup.
      name: Senders
    - description: Scoped API key lifecycle management.
      name: API Keys
    - description: Prepaid billing accounts, top-up and payment-method sessions, funding documents, and usage posture.
      name: Billing
    - description: Webhook endpoints, event delivery, signing, and redelivery.
      name: Webhooks
    - description: Minimal transactional delivery summaries.
      name: Reporting
    - description: Workspace, capability, and entitlement discovery.
      name: Platform
x-ctct-contract-posture:
    authentication: api_key_bearer_required
    authorization:
        - api_key_scope_gate
        - openfga_workspace_action_check
        - entitlement_gate
    authorization_note: |
        API key scopes are customer-facing grant labels. Runtime authorization must still evaluate the corresponding OpenFGA action against the workspace, organization, and resource context before executing the request.
    implementation_note: Phase 0-4 preview endpoints are implemented by the dedicated public-api REST adapter; GA hardening, production-scale evidence, and production-readiness operator proof remain open.
    rest_runtime_relationship: sibling_adapter_to_public_mcp
    status: preview_runtime_baseline
