{
  "openapi": "3.1.0",
  "info": {
    "title": "Api",
    "version": "0.1.0",
    "description": "Email Security Gateway API"
  },
  "servers": [
    {
      "url": "/api",
      "description": "Base API path"
    }
  ],
  "tags": [
    {
      "name": "health",
      "description": "Health operations"
    },
    {
      "name": "gateway",
      "description": "Email payload validation and policy checks"
    }
  ],
  "paths": {
    "/v1/admin/customer-recipient-suppressions/{keyId}/clear": {
      "post": {
        "operationId": "clearAdminCustomerRecipientSuppression",
        "tags": [
          "gateway"
        ],
        "summary": "Clear one customer-scoped recipient suppression after manual review",
        "description": "Requires the administrator session and existing admin mutation header. The address is hashed in memory; deletion and a reason-only audit entry commit together. No keys are created or plans changed.",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "parameters": [
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerSuppressionClearInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Review committed, including a reason-only audit entry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerSuppressionClearResult"
                }
              }
            }
          },
          "400": {
            "description": "Address, non-personal review reason and explicit confirmation required"
          },
          "401": {
            "description": "Administrator session required"
          },
          "403": {
            "description": "Admin mutation header required"
          },
          "404": {
            "description": "Unknown key reference"
          },
          "503": {
            "description": "Review storage unavailable"
          }
        }
      }
    },
    "/v1/admin/checkout-claim-recovery": {
      "post": {
        "operationId": "recoverAdminCheckoutClaim",
        "tags": [
          "gateway"
        ],
        "summary": "Reopen exactly one existing unclaimed paid checkout claim",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutClaimRecoveryInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing claim reopened or original recovery replayed; never returns a key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "expiresAt": {
                      "type": "string"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "expiresAt",
                    "replayed"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Administrator session required"
          },
          "403": {
            "description": "Administrator mutation guard required"
          },
          "409": {
            "description": "Claim not eligible for recovery"
          },
          "503": {
            "description": "Recovery outcome unconfirmed"
          }
        }
      }
    },
    "/v1/admin/sender-reputation": {
      "get": {
        "operationId": "getAdminSenderReputation",
        "tags": [
          "gateway"
        ],
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "summary": "Private sender reputation states and review history",
        "responses": {
          "200": {
            "description": "Reputation states, without credentials or recipient data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SenderReputationList"
                }
              }
            }
          },
          "401": {
            "description": "Administrator session required"
          }
        }
      }
    },
    "/v1/admin/sender-reputation/{keyId}/unpause": {
      "post": {
        "operationId": "unpauseAdminSenderReputation",
        "tags": [
          "gateway"
        ],
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "summary": "Reviewed un-pause into restricted probation",
        "parameters": [
          {
            "in": "path",
            "name": "keyId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
            }
          },
          {
            "in": "header",
            "name": "x-sentrisend-admin-request",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SenderReputationReview"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reviewed key is on probation, not unrestricted sending",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "stage"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "stage": {
                      "type": "string",
                      "enum": [
                        "probation"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid review input"
          },
          "401": {
            "description": "Administrator session required"
          },
          "403": {
            "description": "Same-origin administrator mutation required"
          },
          "409": {
            "description": "Stale or non-paused state"
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "operationId": "gatewayHealth",
        "tags": [
          "health"
        ],
        "summary": "Gateway liveness health check",
        "responses": {
          "200": {
            "description": "Gateway is serving requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayHealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/v1/validate": {
      "post": {
        "operationId": "validateEmail",
        "tags": [
          "gateway"
        ],
        "summary": "Validate a recipient without sending email",
        "description": "Authenticates a customer ss_live_ key against public.customer_api_keys and\nconsumes exactly one monthly request quota unit for each admitted call. Checks syntax,\nthe offline disposable-domain list, and live DNS MX records.\nLive DNS and database access have no fixed response-time guarantee.\nOnly offline disposable-list matches return DISPOSABLE_DOMAIN.\nNXDOMAIN returns DOMAIN_NOT_FOUND. Missing MX and A records return\nNO_MX_RECORDS; an explicit null MX also rejects without A fallback.\nA usable IPv4 A record is accepted as a DNS-only implicit MX fallback.\nTransient DNS failures/timeouts fail open with DNS_INCONCLUSIVE and MEDIUM risk.\nOptional quality hints never change allowed or risk_score. suggested_domain\nis present only for an exact match in the curated typo map. advisories may\ncontain ROLE_ACCOUNT for selected role-like local parts. Gmail plus-tags\nand dots remain part of the submitted address; no mailbox or SMTP probe is made.\nInvalid input returns an error object without an allowed field.\nNo SMTP server or mailbox probing is performed.\nA recipient with a retained hard bounce or complaint in this customer's\naccount returns RECIPIENT_SUPPRESSED_FOR_CUSTOMER. Suppression memory is\nnot shared between customer accounts. A suppression lookup failure returns\nretryable HTTP 503 before charging quota.\nShared token buckets limit each key to 120 requests/minute sustained\nwith a burst of 20; IP ingress is limited to 600/minute with a burst of 100.\nRate limits run before customer authentication and DNS. HTTP 429 responses\ncontain no allowed field and include Retry-After when rate-limited.\n",
        "security": [
          {
            "SentriSendBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailValidationInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Usable MX/A records, or fail-open inconclusive DNS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailValidationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid email syntax, rejected domain, or customer-scoped recipient suppression",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/EmailValidationResult"
                    },
                    {
                      "$ref": "#/components/schemas/EmailValidationInputError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or unknown customer key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Inactive customer key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Customer quota exhausted or validation request rate limited",
            "headers": {
              "Retry-After": {
                "description": "Seconds until retry when request rate limited",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/QuotaExceededResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ValidationRateLimitResponse"
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Customer authentication, rate-counter, or recipient suppression service temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/CustomerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/RecipientSuppressionUnavailableResponse"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/": {
      "get": {
        "operationId": "gatewayStatus",
        "tags": [
          "gateway"
        ],
        "summary": "Gateway status",
        "description": "Returns the current gateway mode and connectivity status.",
        "responses": {
          "200": {
            "description": "Gateway status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayStatus"
                }
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "operationId": "healthCheck",
        "tags": [
          "health"
        ],
        "summary": "Health check",
        "description": "Returns server health status",
        "responses": {
          "200": {
            "description": "Healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/checkout/pro": {
      "get": {
        "operationId": "legacyProCheckoutRedirect",
        "tags": [
          "gateway"
        ],
        "summary": "Redirect legacy Pro checkout links to pricing",
        "responses": {
          "303": {
            "description": "Legacy checkout links return to the pricing page without creating a Stripe session",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createProCheckout",
        "tags": [
          "gateway"
        ],
        "summary": "Create a Pro Checkout Session",
        "description": "Starts a same-origin Pro checkout. A repeated purchaseAttemptId from the\nsame client IP reuses the same Stripe idempotency key. Requests are limited\nto five distinct purchase attempts per IP in ten minutes. An optional active\ncustomer API key identifies an existing Pro customer and prefills a verified\nFree key owner's email.\n",
        "parameters": [
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^https?://[^/]+$"
            }
          },
          {
            "in": "header",
            "name": "x-api-key",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^ss_live_[A-Za-z0-9]+$",
              "maxLength": 256
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProCheckoutAttemptInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stripe Checkout URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutSessionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid checkout attempt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutStartErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Supplied customer API key is invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutStartErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Same-origin request required or supplied key is inactive",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutStartErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "The supplied key already has an active Pro plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlreadyProErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Checkout attempt rate limit reached",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutStartErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Checkout is not open or is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutStartErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/checkout/status": {
      "get": {
        "operationId": "getProCheckoutStatus",
        "tags": [
          "gateway"
        ],
        "summary": "Check whether Pro checkout is open",
        "responses": {
          "200": {
            "description": "Current process-startup checkout setting",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": "string",
                      "enum": [
                        "not_open",
                        "schema_unavailable"
                      ],
                      "description": "Present only when checkout is disabled."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/checkout/claim-key": {
      "get": {
        "operationId": "claimCheckoutKey",
        "tags": [
          "gateway"
        ],
        "summary": "Claim a one-time customer API key after checkout",
        "parameters": [
          {
            "name": "session_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^cs_(live|test)_[A-Za-z0-9]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One-time customer API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutClaimResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid checkout session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutClaimErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Checkout payment is not complete",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutClaimErrorResponse"
                }
              }
            }
          },
          "410": {
            "description": "Claim expired or already disclosed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutClaimErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Checkout fulfillment is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutClaimErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/request-key": {
      "post": {
        "operationId": "requestFreeKey",
        "tags": [
          "gateway"
        ],
        "summary": "Request an email-confirmed free key or rotate an existing one",
        "description": "Requires a valid Turnstile token and applies the same recipient validation as /v1/validate. Always responds with the same generic HTTP 200, including invalid, limited, or ineligible requests. A single-use link expires after 30 minutes; opening it never activates a key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FreeKeyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generic acknowledgment, with no account or eligibility disclosure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeKeyRequestResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/customer/free-key": {
      "post": {
        "operationId": "requestLegacyFreeKey",
        "deprecated": true,
        "tags": [
          "gateway"
        ],
        "summary": "Legacy alias for requesting an email-confirmed free key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FreeKeyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generic acknowledgment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeKeyRequestResponse"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/turnstile-config": {
      "get": {
        "operationId": "getSandboxTurnstileConfig",
        "tags": [
          "gateway"
        ],
        "summary": "Get the public Turnstile site key for free-key requests",
        "responses": {
          "200": {
            "description": "The public widget site key, or empty when not configured",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "siteKey": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "siteKey"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/verify": {
      "get": {
        "operationId": "showSandboxVerification",
        "tags": [
          "gateway"
        ],
        "summary": "Display a non-redeeming confirmation page",
        "description": "The token remains in the URL fragment and is submitted only after a deliberate click. The response is never cached.",
        "responses": {
          "200": {
            "description": "Confirmation page",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/v1/customer/free-key/verify": {
      "post": {
        "operationId": "verifyFreeKey",
        "tags": [
          "gateway"
        ],
        "summary": "Redeem a one-time email verification link",
        "description": "Atomically consumes the token and creates a real free key with 100 requests per rolling month. The plaintext key is returned only once.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FreeKeyVerificationInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Newly issued free API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeKeyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid verification token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "An active free key already exists for the verified email",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "410": {
            "description": "Verification link expired or already used",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Key provisioning is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/send": {
      "post": {
        "operationId": "sendEmail",
        "tags": [
          "gateway"
        ],
        "summary": "Send an email through the gateway",
        "description": "Customer keys only; the administrator master key is never accepted here. Free keys can send only to their verified owner and at most 10 messages per UTC day, in addition to the 100-per-month allowance. Checks address syntax, blocks disposable, nonexistent and no-MX/no-A recipient domains before upstream handoff. Transient DNS uncertainty fails open; these checks do not verify mailbox existence. A promotional message without an unsubscribe link receives a non-blocking HIGH advisory; other blocking policies still apply. The existing complianceProof and receipt fields remain HMAC values and are not publicly verifiable. When public receipts are enabled, publicReceipt is an Ed25519-signed record of provider acceptance, not delivery; receiptOpening is returned separately for checking the recipient and message commitments.",
        "security": [
          {
            "SentriSendApiKey": []
          },
          {
            "SentriSendBearer": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Stable caller-generated key reused when retrying the same logical email. SentriSend generates a per-request fallback when omitted.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "pattern": "^[A-Za-z0-9._:-]+$"
            }
          },
          {
            "name": "x-sentrisend-white-label",
            "in": "header",
            "required": false,
            "description": "Requests removal of the SentriSend security footer. Honoured only for API keys with an active Pro white-label entitlement.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailPayload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delivery provider accepted the message and its security audit was confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailPassedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or blocked disposable, nonexistent or no-MX/no-A recipient domain",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/DisposableDomainRejectedResponse"
                    },
                    {
                      "$ref": "#/components/schemas/SendDomainRejectedResponse"
                    },
                    {
                      "$ref": "#/components/schemas/CustomerRecipientSuppressedResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "SentriSend API key was missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "403": {
            "description": "Payload was blocked by a security policy or free-key recipient is not verified (RECIPIENT_NOT_VERIFIED)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/EmailBlockedResponse"
                    },
                    {
                      "$ref": "#/components/schemas/RecipientNotVerifiedResponse"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance reached, or free-key daily send cap reached (10 per UTC day).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/QuotaExceededResponse"
                    },
                    {
                      "$ref": "#/components/schemas/DailySendCapResponse"
                    }
                  ]
                }
              }
            }
          },
          "502": {
            "description": "The upstream email provider could not deliver the approved message",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailDeliveryFailedResponse"
                }
              }
            }
          },
          "503": {
            "description": "A required service was unavailable, or a provider-accepted email's security audit could not be confirmed (do not automatically resend)",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ApiKeyUnavailableResponse"
                    },
                    {
                      "$ref": "#/components/schemas/EmailProviderErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/EmailAuditUnconfirmedResponse"
                    },
                    {
                      "$ref": "#/components/schemas/EmailDeliveryUnconfirmedResponse"
                    },
                    {
                      "$ref": "#/components/schemas/RecipientSuppressionUnavailableResponse"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/receipts/keys": {
      "get": {
        "operationId": "listPublicSendReceiptKeys",
        "tags": [
          "gateway"
        ],
        "summary": "List public keys for SentriSend send receipts",
        "description": "Returns public Ed25519 keys used to check SentriSend public send receipt signatures. No private signing key is returned.",
        "responses": {
          "200": {
            "description": "Public signing keys currently published by SentriSend",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSendReceiptKeySet"
                }
              }
            }
          }
        }
      }
    },
    "/v1/receipts/readiness": {
      "get": {
        "operationId": "getPublicSendReceiptReadiness",
        "tags": [
          "gateway"
        ],
        "summary": "Check public send receipt signing readiness",
        "description": "Checks whether the configured private signing key can produce a receipt that verifies with a published public key. Requires no API key, accesses no customer data, sends no email and returns no key material or receipt.",
        "responses": {
          "200": {
            "description": "Signing readiness and a non-sensitive reason category",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSendReceiptReadiness"
                }
              }
            }
          }
        }
      }
    },
    "/v1/receipts/verify": {
      "post": {
        "operationId": "verifyPublicSendReceipt",
        "tags": [
          "gateway"
        ],
        "summary": "Check a SentriSend public send receipt signature",
        "description": "Checks the signed receipt with published SentriSend public keys. This endpoint receives only the compact receipt string; decoded content, recipient details, message content and receipt-opening data are checked in the caller's browser and are not sent here.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicSendReceiptVerificationInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whether the receipt signature matches a published key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSendReceiptVerificationResult"
                }
              }
            }
          },
          "400": {
            "description": "Request body is not valid JSON or does not contain a receipt string"
          },
          "413": {
            "description": "Receipt request exceeds the 16 KB limit"
          },
          "429": {
            "description": "Per-IP receipt verification rate limit reached"
          },
          "503": {
            "description": "Verification or rate-limit service is temporarily unavailable"
          }
        }
      }
    },
    "/v1/attestations/{proofHash}": {
      "get": {
        "operationId": "getFinancialAttestation",
        "tags": [
          "gateway"
        ],
        "summary": "Look up a public financial attestation",
        "description": "Records a verification-page view. A matching record alone does not establish that a recipient's email is unchanged.",
        "parameters": [
          {
            "name": "proofHash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-f0-9]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stored attestation metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FinancialAttestationRecord"
                }
              }
            }
          },
          "404": {
            "description": "No attestation exists for this hash",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Attestation lookup is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/attestations/{proofHash}/verify": {
      "post": {
        "operationId": "compareFinancialAttestation",
        "tags": [
          "gateway"
        ],
        "summary": "Compare financial coordinates in a received message against its attestation",
        "description": "Extracts and canonicalizes submitted financial claims without storing or returning them.",
        "parameters": [
          {
            "name": "proofHash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-f0-9]{64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FinancialClaimComparisonInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whether the supplied financial coordinates match the attested coordinates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FinancialClaimComparisonResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid comparison input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "No attestation exists for this hash",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many comparison attempts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Attestation lookup is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/send/batch": {
      "post": {
        "operationId": "sendEmailBatch",
        "tags": [
          "gateway"
        ],
        "summary": "Disabled persistent batch endpoint",
        "description": "Persistent batch delivery is disabled to keep SentriSend fully compatible with Autoscale. Use POST /v1/send for request-scoped delivery.",
        "deprecated": true,
        "security": [
          {
            "SentriSendApiKey": []
          },
          {
            "SentriSendBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailBatchPayload"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Batch accepted for processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailBatchAcceptedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Batch failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "SentriSend API key was missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "410": {
            "description": "Persistent batch delivery is disabled on Autoscale",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchDisabledResponse"
                }
              }
            }
          },
          "503": {
            "description": "Queue or API-key storage is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyUnavailableResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batches/{batchId}": {
      "get": {
        "operationId": "getEmailBatch",
        "tags": [
          "gateway"
        ],
        "summary": "Disabled persistent batch status endpoint",
        "description": "Persistent batch delivery is disabled to keep SentriSend fully compatible with Autoscale.",
        "deprecated": true,
        "security": [
          {
            "SentriSendApiKey": []
          },
          {
            "SentriSendBearer": []
          }
        ],
        "parameters": [
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9-]{36}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current recipient-level batch progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailBatchStatusResponse"
                }
              }
            }
          },
          "401": {
            "description": "SentriSend API key was missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Batch was not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchNotFoundResponse"
                }
              }
            }
          },
          "410": {
            "description": "Persistent batch delivery is disabled on Autoscale",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchDisabledResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/dashboard": {
      "get": {
        "operationId": "getDashboard",
        "tags": [
          "gateway"
        ],
        "summary": "Security dashboard data",
        "description": "Returns public aggregate gateway metrics. Individual security audit events remain restricted to the private control plane.",
        "responses": {
          "200": {
            "description": "Current security dashboard data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecurityDashboard"
                }
              }
            }
          },
          "503": {
            "description": "Audit data is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DashboardUnavailableResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/customer/telemetry": {
      "get": {
        "operationId": "getCustomerTelemetry",
        "tags": [
          "gateway"
        ],
        "summary": "Retrieve customer dispatch telemetry",
        "description": "Returns only events owned by the authenticated customer API key.",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Customer plan, quota, and bounded redacted events",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerTelemetry"
                }
              }
            }
          },
          "401": {
            "description": "Invalid customer API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Customer telemetry is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/customer/supabase-hooks": {
      "get": {
        "operationId": "listCustomerSupabaseHooks",
        "tags": [
          "gateway"
        ],
        "summary": "List Supabase Before User Created hooks for the authenticated key",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Hook configuration, request counts and endpoint URLs; signing secrets are never returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupabaseHookList"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive customer API key"
          },
          "503": {
            "description": "Hook settings unavailable"
          }
        }
      },
      "post": {
        "operationId": "createCustomerSupabaseHook",
        "tags": [
          "gateway"
        ],
        "summary": "Create a Supabase Before User Created hook",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "New disabled hook with endpoint URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupabaseHookCreated"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive customer API key"
          },
          "503": {
            "description": "Hook could not be created"
          }
        }
      }
    },
    "/v1/customer/supabase-hooks/{hookId}/secret": {
      "put": {
        "operationId": "saveCustomerSupabaseHookSecret",
        "tags": [
          "gateway"
        ],
        "summary": "Encrypt or rotate a Supabase signing secret",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "hookId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F-]{36}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SupabaseHookSecretInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Secret saved; value is never returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "saved"
                  ],
                  "properties": {
                    "saved": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid signing secret"
          },
          "401": {
            "description": "Invalid or inactive customer API key"
          },
          "404": {
            "description": "Hook not found"
          },
          "503": {
            "description": "Secret could not be saved"
          }
        }
      }
    },
    "/v1/customer/supabase-hooks/{hookId}": {
      "patch": {
        "operationId": "updateCustomerSupabaseHook",
        "tags": [
          "gateway"
        ],
        "summary": "Enable or disable a Supabase hook",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "hookId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F-]{36}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SupabaseHookEnabledInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Hook status updated"
          },
          "401": {
            "description": "Invalid or inactive customer API key"
          },
          "404": {
            "description": "Hook not found"
          },
          "409": {
            "description": "Save a signing secret before enabling the hook"
          },
          "503": {
            "description": "Hook could not be updated"
          }
        }
      },
      "delete": {
        "operationId": "deleteCustomerSupabaseHook",
        "tags": [
          "gateway"
        ],
        "summary": "Delete a hook and its request history",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "hookId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F-]{36}$"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Hook deleted"
          },
          "401": {
            "description": "Invalid or inactive customer API key"
          },
          "404": {
            "description": "Hook not found"
          },
          "503": {
            "description": "Hook could not be deleted"
          }
        }
      }
    },
    "/v1/customer/supabase-hooks/{hookId}/requests": {
      "get": {
        "operationId": "listCustomerSupabaseHookRequests",
        "tags": [
          "gateway"
        ],
        "summary": "Read recent domain-only hook request records",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "hookId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F-]{36}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent outcomes, reason categories and email domains only",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupabaseHookRequests"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive customer API key"
          },
          "503": {
            "description": "Request history unavailable"
          }
        }
      }
    },
    "/v1/customer/supabase-hooks/{hookId}/test": {
      "post": {
        "operationId": "sendCustomerSupabaseHookTestEvent",
        "tags": [
          "gateway"
        ],
        "summary": "Sign a sample event and exercise the hook endpoint",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "hookId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F-]{36}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signature and validation result without returning a secret or sample address",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "outcome",
                    "status"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "outcome": {
                      "type": "string"
                    },
                    "status": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive customer API key"
          },
          "409": {
            "description": "Hook secret must be saved and hook enabled"
          },
          "503": {
            "description": "Test event could not be completed"
          }
        }
      }
    },
    "/hooks/supabase/before-user-created/{hookPathId}": {
      "post": {
        "operationId": "handleSupabaseBeforeUserCreated",
        "tags": [
          "gateway"
        ],
        "summary": "Verify Supabase Auth Before User Created and preflight its email",
        "description": "Checks Standard Webhooks signatures and fresh timestamps before reading user.email.\nAllowed or fail-open outcomes return an empty JSON object. Definite validation\nfailures return a generic 400. Requests without user.email are allowed and logged\nas no_email_to_check. Unknown, disabled or unconfigured endpoints also allow signup.\nRequest records retain only time, outcome, reason category and email domain.\n",
        "parameters": [
          {
            "in": "path",
            "name": "hookPathId",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          },
          {
            "in": "header",
            "name": "webhook-id",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          },
          {
            "in": "header",
            "name": "webhook-timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "webhook-signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SupabaseBeforeUserCreatedPayload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signup continues when allowed, after a fail-open, if no email is present, or for an unknown/disabled endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Email rejected with generic message"
          },
          "401": {
            "description": "Missing, stale, invalid or replayed webhook signature"
          },
          "429": {
            "description": "Per-hook rate limit exceeded"
          }
        }
      }
    },
    "/v1/customer/billing-portal": {
      "post": {
        "operationId": "createCustomerBillingPortal",
        "tags": [
          "gateway"
        ],
        "summary": "Create a customer billing portal session",
        "description": "Creates a Stripe portal session for the customer associated with the API key.",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Billing portal URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingPortalResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid customer API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Billing portal is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/customer/attestation-identity": {
      "get": {
        "operationId": "getCustomerAttestationIdentity",
        "tags": [
          "gateway"
        ],
        "summary": "View the company identity associated with a customer key",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current request and review status, if any",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerAttestationIdentityResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid customer API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Identity service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "requestCustomerAttestationIdentity",
        "tags": [
          "gateway"
        ],
        "summary": "Submit or replace a customer company identity for manual review",
        "security": [
          {
            "SentriSendApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerAttestationIdentityInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request now pending review; prior approval is withdrawn",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerAttestationIdentityResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or reserved identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid customer API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Identity service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/dispatch-recovery": {
      "get": {
        "operationId": "getAdminDispatchRecovery",
        "tags": [
          "gateway"
        ],
        "summary": "Private unresolved customer sends and recovery audit history",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Unresolved sends and recent administrator decisions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminDispatchRecoveryResponse"
                }
              }
            }
          },
          "401": {
            "description": "Administrator session required"
          },
          "503": {
            "description": "Recovery queue unavailable"
          }
        }
      }
    },
    "/v1/admin/dispatch-recovery/{keyId}/decision": {
      "post": {
        "operationId": "decideAdminDispatchRecovery",
        "tags": [
          "gateway"
        ],
        "summary": "Record an independently reviewed provider outcome without resending",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "parameters": [
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminDispatchRecoveryDecisionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Durable decision, with accepted accounting status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminDispatchRecoveryOutcome"
                }
              }
            }
          },
          "400": {
            "description": "Invalid evidence or decision"
          },
          "401": {
            "description": "Administrator session required"
          },
          "403": {
            "description": "Mutation header required"
          },
          "409": {
            "description": "Dispatch changed, still running, or evidence does not match"
          },
          "503": {
            "description": "Recovery unavailable; do not resend"
          }
        }
      }
    },
    "/v1/admin/dispatch-recovery/{keyId}/retry-accounting": {
      "post": {
        "operationId": "retryAdminDispatchAccounting",
        "tags": [
          "gateway"
        ],
        "summary": "Retry accounting only for a durably recorded provider acceptance",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "parameters": [
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminDispatchAccountingRetryInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted accounting recovery status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminDispatchRecoveryOutcome"
                }
              }
            }
          },
          "400": {
            "description": "Invalid dispatch reference"
          },
          "401": {
            "description": "Administrator session required"
          },
          "403": {
            "description": "Mutation header required"
          },
          "409": {
            "description": "No matching confirmed acceptance"
          },
          "503": {
            "description": "Recovery unavailable"
          }
        }
      }
    },
    "/v1/admin/attestation-identities": {
      "get": {
        "operationId": "getAdminAttestationIdentities",
        "tags": [
          "gateway"
        ],
        "summary": "List pending and recently reviewed customer company identities",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Review queue and recent decisions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminAttestationIdentitiesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Administrator session required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Review queue unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/attestation-identities/{keyId}/decision": {
      "post": {
        "operationId": "decideAdminAttestationIdentity",
        "tags": [
          "gateway"
        ],
        "summary": "Approve or reject a pending request, or revoke an approved identity",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "parameters": [
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminAttestationDecisionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated review state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerAttestationIdentityResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid decision",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Administrator session required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Request not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Request already reviewed or sender domain already approved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Review service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/session": {
      "get": {
        "operationId": "getAdminSession",
        "tags": [
          "gateway"
        ],
        "summary": "Check the private administrator session",
        "responses": {
          "200": {
            "description": "Current administrator session status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminSessionResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createAdminSession",
        "tags": [
          "gateway"
        ],
        "summary": "Start a private administrator session",
        "description": "Exchanges the server-configured administrator token for a signed HttpOnly session cookie.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminSessionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Administrator session created",
            "headers": {
              "Set-Cookie": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminSessionResponse"
                }
              }
            }
          },
          "401": {
            "description": "Administrator token was invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many authentication attempts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          },
          "503": {
            "description": "Administrator authentication is unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteAdminSession",
        "tags": [
          "gateway"
        ],
        "summary": "End the private administrator session",
        "parameters": [
          {
            "name": "x-sentrisend-admin-request",
            "in": "header",
            "required": true,
            "description": "Same-origin mutation marker required for CSRF protection.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Administrator session ended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminSessionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/api-key": {
      "get": {
        "operationId": "getAdminApiKey",
        "tags": [
          "gateway"
        ],
        "summary": "Retrieve the active API key",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Active API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "401": {
            "description": "Administrator authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          },
          "503": {
            "description": "API key storage is unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyUnavailableResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/api-key/roll": {
      "post": {
        "operationId": "rollAdminApiKey",
        "tags": [
          "gateway"
        ],
        "summary": "Rotate the active API key",
        "description": "Immediately replaces the key used by gateway and SMTP clients.",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "parameters": [
          {
            "name": "x-sentrisend-admin-request",
            "in": "header",
            "required": true,
            "description": "Same-origin mutation marker required for CSRF protection.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Newly activated API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "401": {
            "description": "Administrator authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          },
          "503": {
            "description": "API key storage is unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyUnavailableResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/dashboard": {
      "get": {
        "operationId": "getAdminDashboard",
        "tags": [
          "gateway"
        ],
        "summary": "Retrieve private security audit data",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Aggregate metrics and individual audit events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecurityDashboard"
                }
              }
            }
          },
          "401": {
            "description": "Administrator authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          },
          "503": {
            "description": "Audit data is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DashboardUnavailableResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/diagnostic-send": {
      "post": {
        "operationId": "runFounderDiagnostic",
        "tags": [
          "gateway"
        ],
        "summary": "Run a private founder gateway diagnostic",
        "description": "Requires an administrator session and same-origin mutation header. The active gateway master key is used only on the server and is never returned. The verified mode sends a real email; the disposable mode tests the offline mailinator block.",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "parameters": [
          {
            "name": "x-sentrisend-admin-request",
            "in": "header",
            "required": true,
            "description": "Same-origin mutation marker required for CSRF protection.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FounderDiagnosticInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Gateway diagnostic result, including the gateway's actual HTTP status and JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FounderDiagnosticResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid diagnostic input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Administrator authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          },
          "403": {
            "description": "Same-origin mutation header is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          },
          "503": {
            "description": "Diagnostic execution failed or its outcome is unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/audit/{proof}": {
      "get": {
        "operationId": "getFounderAuditRecord",
        "tags": [
          "gateway"
        ],
        "summary": "View a private security audit record by compliance proof",
        "description": "Reads a redacted security_audit_logs record using the server's privileged Supabase connection.",
        "security": [
          {
            "SentriSendAdminSession": []
          }
        ],
        "parameters": [
          {
            "name": "proof",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Redacted audit record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecurityAuditEvent"
                }
              }
            }
          },
          "400": {
            "description": "Invalid compliance proof",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Administrator authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnauthorizedResponse"
                }
              }
            }
          },
          "404": {
            "description": "No matching audit record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Audit storage is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "SentriSendApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "SentriSendBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "SentriSend API key"
      },
      "SentriSendAdminSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "ss_admin"
      }
    },
    "schemas": {
      "SenderReputationReview": {
        "type": "object",
        "required": [
          "reason",
          "confirmed",
          "expectedChangedAt"
        ],
        "properties": {
          "reason": {
            "type": "string",
            "minLength": 10,
            "maxLength": 500
          },
          "confirmed": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "expectedChangedAt": {
            "type": "string"
          }
        }
      },
      "SenderReputationList": {
        "type": "object",
        "required": [
          "keys",
          "history"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "keyId",
                "stage",
                "changedAt",
                "reasonCodes"
              ],
              "properties": {
                "keyId": {
                  "type": "string"
                },
                "stage": {
                  "type": "string",
                  "enum": [
                    "normal",
                    "warn",
                    "slow",
                    "paused",
                    "probation"
                  ]
                },
                "changedAt": {
                  "type": "string"
                },
                "reasonCodes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "history": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "keyId",
                "fromStage",
                "toStage",
                "actor",
                "reason",
                "createdAt"
              ],
              "properties": {
                "keyId": {
                  "type": "string"
                },
                "fromStage": {
                  "type": "string"
                },
                "toStage": {
                  "type": "string"
                },
                "actor": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "RecipientNotVerifiedResponse": {
        "type": "object",
        "required": [
          "success",
          "error",
          "code"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "RECIPIENT_NOT_VERIFIED"
            ]
          }
        }
      },
      "DailySendCapResponse": {
        "type": "object",
        "required": [
          "success",
          "error",
          "code"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "DAILY_SEND_LIMIT"
            ]
          }
        }
      },
      "SendDomainRejectedResponse": {
        "type": "object",
        "required": [
          "success",
          "error",
          "code",
          "reason",
          "allowed",
          "disposable",
          "risk_score",
          "complianceProof"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "DOMAIN_NOT_FOUND",
              "NO_MX_RECORDS"
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "DOMAIN_NOT_FOUND",
              "NO_MX_RECORDS"
            ]
          },
          "allowed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "disposable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "risk_score": {
            "type": "string",
            "enum": [
              "HIGH"
            ]
          },
          "complianceProof": {
            "type": "string"
          }
        }
      },
      "ValidationRateLimitResponse": {
        "type": "object",
        "required": [
          "success",
          "error",
          "code",
          "retry_after"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "RATE_LIMITED"
            ]
          },
          "retry_after": {
            "type": "number",
            "minimum": 1
          }
        }
      },
      "GatewayHealthStatus": {
        "type": "object",
        "required": [
          "status",
          "service",
          "timestamp"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "healthy"
            ]
          },
          "service": {
            "type": "string",
            "enum": [
              "SentriSend Gateway"
            ]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EmailValidationInput": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "minLength": 3,
            "maxLength": 254,
            "description": "A single bare email address, without a display name."
          }
        }
      },
      "EmailValidationResult": {
        "type": "object",
        "required": [
          "allowed",
          "disposable",
          "risk_score"
        ],
        "properties": {
          "allowed": {
            "type": "boolean"
          },
          "disposable": {
            "type": "boolean",
            "description": "True only for an offline disposable-domain list match."
          },
          "reason": {
            "type": "string",
            "enum": [
              "DISPOSABLE_DOMAIN",
              "DOMAIN_NOT_FOUND",
              "NO_MX_RECORDS",
              "DNS_INCONCLUSIVE",
              "RECIPIENT_SUPPRESSED_FOR_CUSTOMER"
            ]
          },
          "risk_score": {
            "type": "string",
            "enum": [
              "HIGH",
              "MEDIUM",
              "LOW"
            ]
          },
          "suggested_domain": {
            "type": "string",
            "minLength": 1,
            "maxLength": 253,
            "description": "Optional likely domain for an exact match in the curated typo map. It never changes the validation verdict."
          },
          "advisories": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "ROLE_ACCOUNT"
              ]
            },
            "description": "Optional non-blocking address-quality advisories. This field does not change allowed or risk_score."
          }
        }
      },
      "EmailValidationInputError": {
        "type": "object",
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "INVALID_EMAIL"
            ]
          }
        }
      },
      "CustomerRecipientSuppressedResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "error",
          "suppressedRecipientPositions"
        ],
        "description": "The whole send is rejected before delivery, monthly quota, daily cap or reputation admission. Positions are one-based indexes in the original to array; a single recipient has position 1. Completed idempotent sends replay their saved result before this check.",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "RECIPIENT_SUPPRESSED_FOR_CUSTOMER"
            ]
          },
          "error": {
            "type": "string"
          },
          "suppressedRecipientPositions": {
            "type": "array",
            "items": {
              "type": "number",
              "minimum": 1
            }
          }
        }
      },
      "RecipientSuppressionUnavailableResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "error"
        ],
        "description": "Temporary fail-closed lookup failure. Retry later; no quota was charged and no email was sent.",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "RECIPIENT_SUPPRESSION_UNAVAILABLE"
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "CustomerSuppressionClearInput": {
        "type": "object",
        "required": [
          "email",
          "reason",
          "confirmed"
        ],
        "properties": {
          "email": {
            "type": "string",
            "minLength": 3,
            "maxLength": 254
          },
          "reason": {
            "type": "string",
            "minLength": 10,
            "maxLength": 500,
            "description": "Non-personal review reason. Do not include addresses, API keys or secrets."
          },
          "confirmed": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "CustomerSuppressionClearResult": {
        "type": "object",
        "required": [
          "ok",
          "cleared"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "cleared": {
            "type": "boolean"
          }
        }
      },
      "AdminDispatchRecoveryItem": {
        "type": "object",
        "required": [
          "keyId",
          "dispatchId",
          "state",
          "startedAt",
          "complianceProof",
          "idempotencyFingerprint",
          "providerReference",
          "legacy",
          "readyForReview",
          "expectedUsage",
          "tier"
        ],
        "properties": {
          "keyId": {
            "type": "string"
          },
          "dispatchId": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "in_flight",
              "accounting_unconfirmed"
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time"
          },
          "complianceProof": {
            "type": [
              "string",
              "null"
            ]
          },
          "idempotencyFingerprint": {
            "type": [
              "string",
              "null"
            ]
          },
          "providerReference": {
            "type": [
              "string",
              "null"
            ]
          },
          "legacy": {
            "type": "boolean"
          },
          "readyForReview": {
            "type": "boolean"
          },
          "expectedUsage": {
            "type": "number",
            "minimum": 0
          },
          "tier": {
            "type": "string"
          }
        }
      },
      "AdminDispatchRecoveryEvent": {
        "type": "object",
        "required": [
          "dispatchId",
          "keyId",
          "decision",
          "source",
          "evidenceReference",
          "reviewNote",
          "providerReference",
          "complianceProof",
          "acceptedAt",
          "decidedAt"
        ],
        "properties": {
          "dispatchId": {
            "type": "string"
          },
          "keyId": {
            "type": "string"
          },
          "decision": {
            "type": "string",
            "enum": [
              "accepted",
              "rejected"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "manual_review",
              "provider_receipt"
            ]
          },
          "evidenceReference": {
            "type": "string"
          },
          "reviewNote": {
            "type": "string"
          },
          "providerReference": {
            "type": [
              "string",
              "null"
            ]
          },
          "complianceProof": {
            "type": [
              "string",
              "null"
            ]
          },
          "acceptedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "decidedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AdminDispatchRecoveryResponse": {
        "type": "object",
        "required": [
          "pending",
          "recent"
        ],
        "properties": {
          "pending": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminDispatchRecoveryItem"
            }
          },
          "recent": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminDispatchRecoveryEvent"
            }
          }
        }
      },
      "AdminDispatchRecoveryDecisionInput": {
        "type": "object",
        "required": [
          "dispatchId",
          "complianceProof",
          "decision",
          "evidenceReference",
          "reviewNote",
          "evidenceVerified"
        ],
        "properties": {
          "dispatchId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "complianceProof": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          },
          "decision": {
            "type": "string",
            "enum": [
              "accepted",
              "rejected"
            ]
          },
          "evidenceReference": {
            "type": "string",
            "minLength": 3,
            "maxLength": 200
          },
          "reviewNote": {
            "type": "string",
            "minLength": 10,
            "maxLength": 500
          },
          "evidenceVerified": {
            "type": "boolean"
          },
          "providerReference": {
            "type": "string",
            "minLength": 3,
            "maxLength": 200
          },
          "acceptedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AdminDispatchAccountingRetryInput": {
        "type": "object",
        "required": [
          "dispatchId",
          "complianceProof"
        ],
        "properties": {
          "dispatchId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "complianceProof": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          }
        }
      },
      "AdminDispatchRecoveryOutcome": {
        "type": "object",
        "required": [
          "keyId",
          "dispatchId",
          "outcome",
          "replayed"
        ],
        "properties": {
          "keyId": {
            "type": "string"
          },
          "dispatchId": {
            "type": "string"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "resolved",
              "usage_pending"
            ]
          },
          "replayed": {
            "type": "boolean"
          }
        }
      },
      "FounderDiagnosticInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "verified",
              "disposable"
            ]
          },
          "recipientEmail": {
            "type": "string",
            "minLength": 3,
            "maxLength": 254,
            "pattern": "^[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+$"
          }
        },
        "required": [
          "mode"
        ]
      },
      "FounderDiagnosticResult": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "verified",
              "disposable"
            ]
          },
          "statusCode": {
            "type": "number"
          },
          "statusText": {
            "type": "string"
          },
          "latencyMs": {
            "type": "number",
            "minimum": 0
          },
          "receipt": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          },
          "receiptVerified": {
            "type": "boolean"
          },
          "auditRecordUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "gatewayResponse": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "mode",
          "statusCode",
          "statusText",
          "latencyMs",
          "receipt",
          "receiptVerified",
          "auditRecordUrl",
          "gatewayResponse"
        ]
      },
      "CustomerAttestationIdentityInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "companyName": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120
          },
          "companyNumber": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{8}$"
          },
          "senderDomain": {
            "type": "string",
            "minLength": 4,
            "maxLength": 253
          }
        },
        "required": [
          "companyName",
          "companyNumber",
          "senderDomain"
        ]
      },
      "CustomerAttestationIdentity": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
          },
          "companyName": {
            "type": "string"
          },
          "companyNumber": {
            "type": "string"
          },
          "senderDomain": {
            "type": "string"
          },
          "jurisdiction": {
            "type": "string",
            "enum": [
              "GB"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "revoked"
            ]
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time"
          },
          "reviewedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "reviewNote": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "companyName",
          "companyNumber",
          "senderDomain",
          "jurisdiction",
          "status",
          "requestedAt",
          "reviewedAt",
          "reviewNote"
        ]
      },
      "CustomerAttestationIdentityResponse": {
        "type": "object",
        "properties": {
          "identity": {
            "$ref": "#/components/schemas/CustomerAttestationIdentity"
          }
        }
      },
      "AdminAttestationReviewItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CustomerAttestationIdentity"
          },
          {
            "type": "object",
            "properties": {
              "keyId": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
              },
              "customerEmail": {
                "type": "string"
              }
            },
            "required": [
              "keyId",
              "customerEmail"
            ]
          }
        ]
      },
      "AdminAttestationIdentitiesResponse": {
        "type": "object",
        "properties": {
          "requests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminAttestationReviewItem"
            }
          }
        },
        "required": [
          "requests"
        ]
      },
      "AdminAttestationDecisionInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "decision": {
            "type": "string",
            "enum": [
              "approved",
              "rejected",
              "revoked"
            ]
          },
          "requestId": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
            "description": "Unique version of the reviewed identity request."
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Exact request timestamp observed in the review queue; prevents approving a replaced request."
          },
          "reviewNote": {
            "type": "string",
            "maxLength": 500
          }
        },
        "required": [
          "decision",
          "requestId",
          "requestedAt"
        ]
      },
      "FinancialAttestationRecord": {
        "type": "object",
        "properties": {
          "proofHash": {
            "type": "string",
            "pattern": "^0x[a-f0-9]{64}$"
          },
          "companyName": {
            "type": "string"
          },
          "companyNumber": {
            "type": "string"
          },
          "jurisdiction": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "verificationCount": {
            "type": "number",
            "minimum": 1
          }
        },
        "required": [
          "proofHash",
          "companyName",
          "companyNumber",
          "jurisdiction",
          "createdAt",
          "verificationCount"
        ]
      },
      "FinancialClaimComparisonInput": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200000,
            "description": "Original received email body or its complete financial coordinates."
          }
        },
        "required": [
          "content"
        ]
      },
      "FinancialClaimComparisonResult": {
        "type": "object",
        "properties": {
          "match": {
            "type": "boolean"
          }
        },
        "required": [
          "match"
        ]
      },
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          }
        },
        "required": [
          "status"
        ]
      },
      "GatewayStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ONLINE"
            ]
          },
          "message": {
            "type": "string"
          },
          "supabaseConnected": {
            "type": "boolean"
          }
        },
        "required": [
          "status",
          "message",
          "supabaseConnected"
        ]
      },
      "SecurityAuditEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "timestamp": {
            "type": [
              "string",
              "null"
            ]
          },
          "eventType": {
            "type": "string"
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "redactedPayload": {
            "type": "object",
            "additionalProperties": true
          },
          "complianceProof": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^(?:sha256:[a-f0-9]{64}|hmac-sha256:v1:[a-f0-9]{64})$"
          }
        },
        "required": [
          "id",
          "timestamp",
          "eventType",
          "reasons",
          "redactedPayload",
          "complianceProof"
        ]
      },
      "SecurityDashboard": {
        "type": "object",
        "properties": {
          "totalEmailsScanned": {
            "type": "number",
            "minimum": 0
          },
          "threatsBlocked": {
            "type": "number",
            "minimum": 0
          },
          "globalThreatSignatures": {
            "type": "number",
            "minimum": 0
          },
          "systemStatus": {
            "type": "string",
            "enum": [
              "Operational"
            ]
          },
          "generatedAt": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SecurityAuditEvent"
            }
          }
        },
        "required": [
          "totalEmailsScanned",
          "threatsBlocked",
          "globalThreatSignatures",
          "systemStatus",
          "generatedAt",
          "events"
        ]
      },
      "DashboardUnavailableResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "CustomerAuditEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "eventType": {
            "type": "string"
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "complianceProof": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "timestamp",
          "eventType",
          "reasons",
          "complianceProof"
        ]
      },
      "SupabaseHookSummary": {
        "type": "object",
        "required": [
          "id",
          "url",
          "enabled",
          "secretSaved",
          "createdAt",
          "lastRequestAt",
          "counts24h",
          "counts30d"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9a-fA-F-]{36}$"
          },
          "url": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "secretSaved": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastRequestAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "counts24h": {
            "$ref": "#/components/schemas/SupabaseHookCounts"
          },
          "counts30d": {
            "$ref": "#/components/schemas/SupabaseHookCounts"
          }
        }
      },
      "SupabaseHookCounts": {
        "type": "object",
        "required": [
          "allowed",
          "blocked",
          "uncheckedFailOpen",
          "invalidSignature",
          "rateLimited"
        ],
        "properties": {
          "allowed": {
            "type": "number",
            "minimum": 0
          },
          "blocked": {
            "type": "number",
            "minimum": 0
          },
          "uncheckedFailOpen": {
            "type": "number",
            "minimum": 0
          },
          "invalidSignature": {
            "type": "number",
            "minimum": 0
          },
          "rateLimited": {
            "type": "number",
            "minimum": 0
          }
        }
      },
      "SupabaseHookList": {
        "type": "object",
        "required": [
          "hooks"
        ],
        "properties": {
          "hooks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SupabaseHookSummary"
            }
          }
        }
      },
      "SupabaseHookCreated": {
        "type": "object",
        "required": [
          "hook"
        ],
        "properties": {
          "hook": {
            "$ref": "#/components/schemas/SupabaseHookSummary"
          }
        }
      },
      "SupabaseHookRequest": {
        "type": "object",
        "required": [
          "time",
          "outcome",
          "reasonCategory",
          "domain"
        ],
        "properties": {
          "time": {
            "type": "string",
            "format": "date-time"
          },
          "outcome": {
            "type": "string"
          },
          "reasonCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "domain": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SupabaseHookRequests": {
        "type": "object",
        "required": [
          "requests"
        ],
        "properties": {
          "requests": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/SupabaseHookRequest"
            }
          }
        }
      },
      "SupabaseHookSecretInput": {
        "type": "object",
        "required": [
          "secret"
        ],
        "properties": {
          "secret": {
            "type": "string",
            "minLength": 20,
            "maxLength": 520,
            "writeOnly": true
          }
        }
      },
      "SupabaseHookEnabledInput": {
        "type": "object",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "SupabaseBeforeUserCreatedPayload": {
        "type": "object",
        "required": [
          "user"
        ],
        "properties": {
          "user": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
              }
            }
          }
        }
      },
      "CustomerTelemetry": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "dispatchCount": {
            "type": "number",
            "minimum": 0
          },
          "dispatchLimit": {
            "type": "number",
            "minimum": 0
          },
          "currentPeriodEnd": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cancelAtPeriodEnd": {
            "type": "boolean"
          },
          "events": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/CustomerAuditEvent"
            }
          }
        },
        "required": [
          "plan",
          "status",
          "dispatchCount",
          "dispatchLimit",
          "currentPeriodEnd",
          "cancelAtPeriodEnd",
          "events"
        ]
      },
      "BillingPortalResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "pattern": "^https://"
          }
        },
        "required": [
          "url"
        ]
      },
      "CustomerErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "QuotaExceededResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "QUOTA_EXCEEDED"
            ]
          }
        },
        "required": [
          "success",
          "error",
          "code"
        ]
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "apiKey": {
            "type": "string",
            "pattern": "^ss_live_[A-Za-z0-9]+$"
          },
          "status": {
            "type": "string",
            "enum": [
              "active"
            ]
          },
          "createdAt": {
            "type": "string"
          }
        },
        "required": [
          "apiKey",
          "status",
          "createdAt"
        ]
      },
      "ApiKeyUnavailableResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "ProCheckoutAttemptInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "purchaseAttemptId": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
          },
          "locale": {
            "type": "string",
            "enum": [
              "en",
              "ja",
              "ko",
              "zh",
              "zh-hk"
            ]
          }
        },
        "required": [
          "purchaseAttemptId",
          "locale"
        ]
      },
      "CheckoutSessionResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "pattern": "^https://"
          }
        },
        "required": [
          "url"
        ]
      },
      "CheckoutStartErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "ORIGIN_REJECTED",
              "INVALID_KEY",
              "CUSTOMER_INACTIVE",
              "RATE_LIMITED",
              "CHECKOUT_NOT_OPEN",
              "CHECKOUT_UNAVAILABLE"
            ]
          }
        },
        "required": [
          "error",
          "code"
        ]
      },
      "AlreadyProErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "ALREADY_ACTIVE_PRO"
            ]
          }
        },
        "required": [
          "error",
          "code"
        ]
      },
      "CheckoutClaimRecoveryInput": {
        "type": "object",
        "properties": {
          "sessionId": {
            "type": "string",
            "pattern": "^cs_(live|test)_[A-Za-z0-9]+$"
          },
          "paymentEmail": {
            "type": "string",
            "minLength": 3,
            "maxLength": 254
          },
          "reason": {
            "type": "string",
            "minLength": 10,
            "maxLength": 300
          },
          "confirmed": {
            "type": "boolean"
          }
        },
        "required": [
          "sessionId",
          "paymentEmail",
          "reason",
          "confirmed"
        ]
      },
      "CheckoutClaimResponse": {
        "type": "object",
        "properties": {
          "apiKey": {
            "type": "string",
            "pattern": "^ss_live_[A-Za-z0-9]+$"
          },
          "status": {
            "type": "string",
            "enum": [
              "active"
            ]
          }
        },
        "required": [
          "apiKey",
          "status"
        ]
      },
      "CheckoutClaimErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "INVALID_SESSION",
              "PAYMENT_NOT_COMPLETE",
              "CLAIM_EXPIRED",
              "KEY_ALREADY_SHOWN",
              "TEMPORARY_FAILURE"
            ]
          }
        },
        "required": [
          "error",
          "code"
        ]
      },
      "FreeKeyInput": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
            "minLength": 3,
            "maxLength": 254
          },
          "locale": {
            "type": "string",
            "enum": [
              "en",
              "ja",
              "ko",
              "zh",
              "zh-hk"
            ]
          },
          "purpose": {
            "type": "string",
            "enum": [
              "issue",
              "regenerate"
            ],
            "default": "issue"
          },
          "turnstileToken": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048
          }
        },
        "required": [
          "email",
          "turnstileToken"
        ]
      },
      "FreeKeyVerificationInput": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "token"
        ]
      },
      "FreeKeyRequestResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      },
      "FreeKeyResponse": {
        "type": "object",
        "properties": {
          "apiKey": {
            "type": "string",
            "pattern": "^ss_live_[A-Za-z0-9]+$"
          },
          "status": {
            "type": "string",
            "enum": [
              "active"
            ]
          },
          "plan": {
            "type": "string",
            "enum": [
              "free"
            ]
          },
          "dispatchLimit": {
            "type": "number",
            "minimum": 100,
            "maximum": 100
          },
          "currentPeriodEnd": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "apiKey",
          "status",
          "plan",
          "dispatchLimit",
          "currentPeriodEnd"
        ]
      },
      "AdminSessionRequest": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "minLength": 32,
            "maxLength": 512
          }
        },
        "required": [
          "token"
        ]
      },
      "AdminSessionResponse": {
        "type": "object",
        "properties": {
          "authenticated": {
            "type": "boolean"
          }
        },
        "required": [
          "authenticated"
        ]
      },
      "AdminUnauthorizedResponse": {
        "type": "object",
        "properties": {
          "authenticated": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "authenticated",
          "error"
        ]
      },
      "UnauthorizedResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "enum": [
              "Unauthorized: Invalid or missing SentriSend API key."
            ]
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "EmailPayload": {
        "type": "object",
        "properties": {
          "to": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^(?:[^<>\\r\\n]+\\s<[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+>|[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+)$"
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^(?:[^<>\\r\\n]+\\s<[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+>|[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+)$"
                },
                "minItems": 1
              }
            ]
          },
          "subject": {
            "type": "string",
            "minLength": 3,
            "maxLength": 100
          },
          "html": {
            "type": "string",
            "minLength": 5
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "description": "Optional UTF-8 plain-text alternative to the HTML body."
          },
          "from": {
            "type": "string",
            "description": "Sender mailbox as a plain email address or a display name followed by an angle-bracketed email address.",
            "pattern": "^(?:[^<>\\r\\n]+\\s<[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+>|[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+)$"
          },
          "reply_to": {
            "type": "string",
            "description": "Optional reply address for recipients. Does not change the verified sender identity.",
            "pattern": "^(?:[^<>\\r\\n]+\\s<[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+>|[^@\\s<>]+@[^@\\s<>]+\\.[^@\\s<>]+)$"
          },
          "intendedUse": {
            "type": "string",
            "default": "General Notification"
          },
          "whiteLabel": {
            "type": "boolean",
            "description": "Requests removal of the SentriSend security footer. Honoured only for API keys with an active Pro white-label entitlement."
          }
        },
        "required": [
          "to",
          "subject",
          "html"
        ]
      },
      "EmailBatchPayload": {
        "type": "object",
        "properties": {
          "emails": {
            "type": "array",
            "minItems": 1,
            "maxItems": 1000,
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/EmailPayload"
                },
                {
                  "type": "object",
                  "properties": {
                    "to": {
                      "type": "string",
                      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
                    }
                  },
                  "required": [
                    "to"
                  ]
                }
              ]
            }
          }
        },
        "required": [
          "emails"
        ]
      },
      "EmailBatchAcceptedResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "QUEUED"
            ]
          },
          "batchId": {
            "type": "string",
            "pattern": "^[a-f0-9-]{36}$"
          },
          "accepted": {
            "type": "number",
            "minimum": 1,
            "maximum": 1000
          },
          "statusUrl": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "status",
          "batchId",
          "accepted",
          "statusUrl"
        ]
      },
      "EmailBatchStatusItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-f0-9-]{36}$"
          },
          "position": {
            "type": "number",
            "minimum": 0
          },
          "status": {
            "type": "string",
            "enum": [
              "QUEUED",
              "DISPATCHING",
              "EMAIL_DELIVERED",
              "DELIVERED_AFTER_RETRY",
              "DELIVERY_FAILED",
              "BLOCKED_THREAT"
            ]
          },
          "attempts": {
            "type": "number",
            "minimum": 0
          },
          "providerId": {
            "type": [
              "string",
              "null"
            ]
          },
          "providerError": {
            "type": [
              "string",
              "null"
            ]
          },
          "complianceProof": {
            "type": "string",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          }
        },
        "required": [
          "id",
          "position",
          "status",
          "attempts",
          "providerId",
          "providerError",
          "complianceProof"
        ]
      },
      "EmailBatchStatusResponse": {
        "type": "object",
        "properties": {
          "batchId": {
            "type": "string",
            "pattern": "^[a-f0-9-]{36}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "QUEUED",
              "PROCESSING",
              "COMPLETED",
              "COMPLETED_WITH_FAILURES"
            ]
          },
          "total": {
            "type": "number",
            "minimum": 1
          },
          "queued": {
            "type": "number",
            "minimum": 0
          },
          "processing": {
            "type": "number",
            "minimum": 0
          },
          "delivered": {
            "type": "number",
            "minimum": 0
          },
          "blocked": {
            "type": "number",
            "minimum": 0
          },
          "failed": {
            "type": "number",
            "minimum": 0
          },
          "createdAt": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailBatchStatusItem"
            }
          }
        },
        "required": [
          "batchId",
          "status",
          "total",
          "queued",
          "processing",
          "delivered",
          "blocked",
          "failed",
          "createdAt",
          "items"
        ]
      },
      "BatchNotFoundResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "BatchDisabledResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "EmailPassedResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "DELIVERED",
              "DELIVERED_AFTER_RETRY"
            ]
          },
          "providerId": {
            "type": [
              "string",
              "null"
            ]
          },
          "attempts": {
            "type": "number",
            "minimum": 1,
            "maximum": 3
          },
          "complianceProof": {
            "type": "string",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          },
          "receipt": {
            "type": "string",
            "description": "The same HMAC compliance proof as complianceProof, retained as an alias for customer integrations.",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          },
          "riskLevel": {
            "type": "string",
            "enum": [
              "LOW",
              "HIGH",
              "CRITICAL"
            ],
            "description": "Highest policy severity for the request. HIGH advisories alone do not block dispatch."
          },
          "riskScore": {
            "type": "number",
            "enum": [
              0,
              75,
              100
            ],
            "description": "Deterministic policy severity index (LOW=0, HIGH=75, CRITICAL=100), not a probability or delivery prediction."
          },
          "advisories": {
            "type": "array",
            "description": "Policy warnings retained even when the message is dispatched.",
            "items": {
              "type": "string"
            }
          },
          "publicReceipt": {
            "type": "string",
            "maxLength": 16000,
            "description": "Optional compact Ed25519 JWS recording provider acceptance and the send checks stated in its payload."
          },
          "receiptOpening": {
            "$ref": "#/components/schemas/PublicSendReceiptOpening"
          }
        },
        "required": [
          "success",
          "status",
          "providerId",
          "attempts",
          "complianceProof",
          "receipt",
          "riskLevel",
          "riskScore",
          "advisories"
        ]
      },
      "PublicSendReceiptKey": {
        "type": "object",
        "required": [
          "kid",
          "kty",
          "crv",
          "x",
          "alg",
          "use",
          "status"
        ],
        "properties": {
          "kid": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "kty": {
            "type": "string",
            "enum": [
              "OKP"
            ]
          },
          "crv": {
            "type": "string",
            "enum": [
              "Ed25519"
            ]
          },
          "x": {
            "type": "string",
            "minLength": 43,
            "maxLength": 43
          },
          "alg": {
            "type": "string",
            "enum": [
              "EdDSA"
            ]
          },
          "use": {
            "type": "string",
            "enum": [
              "sig"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "retired",
              "revoked"
            ]
          }
        }
      },
      "PublicSendReceiptKeySet": {
        "type": "object",
        "required": [
          "keys"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicSendReceiptKey"
            }
          }
        }
      },
      "PublicSendReceiptReadiness": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ready",
          "reason"
        ],
        "properties": {
          "ready": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "enum": [
              "ready",
              "not_configured",
              "configuration_invalid",
              "self_check_failed"
            ]
          }
        }
      },
      "PublicSendReceiptVerificationInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "receipt"
        ],
        "properties": {
          "receipt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16000
          }
        }
      },
      "PublicSendReceiptVerificationResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "signatureMatches",
          "keyId",
          "issuedAt"
        ],
        "properties": {
          "signatureMatches": {
            "type": "boolean"
          },
          "keyId": {
            "type": [
              "string",
              "null"
            ]
          },
          "issuedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "PublicSendReceiptOpening": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "recipientSalt",
          "messageSalt"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "enum": [
              1
            ]
          },
          "recipientSalt": {
            "type": "string",
            "minLength": 43,
            "maxLength": 43
          },
          "messageSalt": {
            "type": "string",
            "minLength": 43,
            "maxLength": 43
          }
        }
      },
      "EmailDeliveryFailedResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "DELIVERY_FAILED"
            ]
          },
          "providerError": {
            "type": "string"
          },
          "attempts": {
            "type": "number",
            "minimum": 1,
            "maximum": 3
          },
          "complianceProof": {
            "type": "string",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          }
        },
        "required": [
          "success",
          "status",
          "providerError",
          "attempts",
          "complianceProof"
        ]
      },
      "EmailDeliveryUnconfirmedResponse": {
        "type": "object",
        "description": "Provider handoff outcome is unknown. Do not automatically resend. Customer dispatches remain blocked for independent administrator review.",
        "required": [
          "success",
          "status",
          "doNotRetry",
          "dispatchId",
          "complianceProof",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "DELIVERY_UNCONFIRMED"
            ]
          },
          "doNotRetry": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "dispatchId": {
            "type": [
              "string",
              "null"
            ]
          },
          "complianceProof": {
            "type": "string",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          },
          "error": {
            "type": "string"
          }
        }
      },
      "EmailAuditUnconfirmedResponse": {
        "type": "object",
        "description": "The provider accepted the email, but audit persistence could not be fully confirmed. Do not automatically resend it.",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "AUDIT_UNCONFIRMED"
            ]
          },
          "deliveryAccepted": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "providerId": {
            "type": [
              "string",
              "null"
            ]
          },
          "complianceProof": {
            "type": "string",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "status",
          "deliveryAccepted",
          "providerId",
          "complianceProof",
          "error"
        ]
      },
      "EmailProviderErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "complianceProof": {
            "type": "string",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          }
        },
        "required": [
          "success",
          "error",
          "complianceProof"
        ]
      },
      "EmailBlockedResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "BLOCKED",
              "BLOCKED_BY_GLOBAL_INTELLIGENCE"
            ]
          },
          "riskLevel": {
            "type": "string",
            "enum": [
              "LOW",
              "HIGH",
              "CRITICAL"
            ]
          },
          "riskScore": {
            "type": "number",
            "enum": [
              0,
              75,
              100
            ],
            "description": "Deterministic policy severity index, not a probability or delivery prediction."
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "complianceProof": {
            "type": "string",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          }
        },
        "required": [
          "success",
          "status",
          "riskLevel",
          "riskScore",
          "reasons",
          "complianceProof"
        ]
      },
      "DisposableDomainRejectedResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "enum": [
              "Disposable email address rejected by pre-flight firewall"
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "DISPOSABLE_DOMAIN_REJECTED"
            ]
          },
          "complianceProof": {
            "type": "string",
            "pattern": "^hmac-sha256:v1:[a-f0-9]{64}$"
          }
        },
        "required": [
          "success",
          "error",
          "code",
          "complianceProof"
        ]
      },
      "ValidationErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "success",
          "error",
          "details"
        ]
      }
    }
  }
}
