{
  "openapi": "3.1.0",
  "info": {
    "title": "Wildmail API",
    "version": "2026-10-11",
    "description": "Customer API for individual Wildmail accounts. Management scopes are recorded in x-required-scope. Account settings, billing, and API key management require a signed-in browser session. Use the hosted application to sign in and manage security factors. Events contain parsed email and can be reshaped with an endpoint payload mapping."
  },
  "servers": [
    {
      "url": "https://wildmail.app",
      "description": "Wildmail application and customer API."
    }
  ],
  "components": {
    "responses": {
      "RequestRateLimitExceeded": {
        "description": "Shared client-IP or account request allowance exhausted. Retry after the indicated number of seconds. Browser authentication errors can use a different response format.",
        "headers": {
          "Cache-Control": {
            "description": "no-store",
            "schema": {
              "type": "string"
            }
          },
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RequestLimitError"
            }
          }
        }
      },
      "RequestRateLimitUnavailable": {
        "description": "Request limiting cannot be enforced. Retry later with backoff.",
        "headers": {
          "Cache-Control": {
            "description": "no-store",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RequestLimitError"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Wildmail scoped kmx_ API token."
      },
      "session": {
        "type": "apiKey",
        "in": "cookie",
        "name": "better-auth.session_token",
        "description": "Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies."
      },
      "pendingFactor": {
        "type": "apiKey",
        "in": "cookie",
        "name": "better-auth.two_factor",
        "description": "Pending second-factor cookie used during sign-in. The hosted application may use the __Secure- cookie prefix."
      }
    },
    "schemas": {
      "RequestLimitError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "rate_limit_exceeded",
              "rate_limit_unavailable"
            ]
          }
        },
        "required": [
          "error",
          "code"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          }
        },
        "required": [
          "error"
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "pageCount": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "pageSize": {
            "type": "integer"
          }
        },
        "required": [
          "page",
          "pageCount",
          "total"
        ]
      },
      "Endpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "failing"
            ]
          },
          "signingSecretHint": {
            "type": "string"
          },
          "secretReady": {
            "type": "boolean"
          },
          "subscribedEvents": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "lastDeliveryAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "payloadMapping": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PayloadMapping"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null uses the standard body. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body."
          }
        },
        "required": [
          "id",
          "name",
          "url",
          "description",
          "status",
          "signingSecretHint",
          "secretReady",
          "subscribedEvents",
          "lastDeliveryAt",
          "payloadMapping"
        ]
      },
      "DomainRoute": {
        "type": "object",
        "description": "An exact local-part route on one customer-owned custom domain. Status reflects whether the account plan and domain allow the route. endpointStatus reports the current endpoint state.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "domainId": {
            "type": "string",
            "format": "uuid"
          },
          "localPart": {
            "type": "string",
            "maxLength": 64,
            "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Matching is case-insensitive. Plus-tags are preserved literally and are not stripped."
          },
          "endpointId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Null when the selected endpoint was deleted. The stored exact route still blocks catch-all fallback until deleted or updated."
          },
          "endpointName": {
            "type": [
              "string",
              "null"
            ]
          },
          "endpointStatus": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "active",
              "paused",
              "failing",
              null
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "suspended"
            ],
            "description": "Free plan downgrades suspend stored routes. A suspended exact match is rejected during SMTP admission and does not use the catch-all."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "domainId",
          "localPart",
          "endpointId",
          "endpointName",
          "endpointStatus",
          "status",
          "createdAt",
          "updatedAt"
        ]
      },
      "Domain": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "mxStatus": {
            "type": "string"
          },
          "billingSuspended": {
            "type": "boolean"
          },
          "ready": {
            "type": "boolean",
            "description": "Domain catch-all readiness: ownership verified, MX valid, billing not suspended, and an active catch-all endpoint assigned. False does not rule out delivery through an active exact-address route."
          },
          "endpointId": {
            "type": [
              "string",
              "null"
            ]
          },
          "endpointName": {
            "type": [
              "string",
              "null"
            ]
          },
          "endpointStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "ownershipVerifiedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastOwnershipCheckAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "mxRecords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "mxCheckedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "dns": {
            "type": "object",
            "properties": {
              "txtHost": {
                "type": "string"
              },
              "txtValue": {
                "type": "string"
              },
              "mxHost": {
                "type": "string"
              },
              "mxPriority": {
                "type": "integer"
              }
            },
            "required": [
              "txtHost",
              "txtValue",
              "mxHost",
              "mxPriority"
            ]
          }
        },
        "required": [
          "id",
          "domain",
          "status",
          "mxStatus",
          "billingSuspended",
          "ready",
          "endpointId",
          "endpointName",
          "endpointStatus",
          "ownershipVerifiedAt",
          "lastOwnershipCheckAt",
          "mxRecords",
          "mxCheckedAt",
          "createdAt",
          "updatedAt",
          "dns"
        ]
      },
      "DeliverySummary": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Delivery"
          },
          {
            "type": "object",
            "properties": {
              "receiptId": {
                "type": "string",
                "pattern": "^[a-f0-9]{24}$"
              },
              "recipients": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "receivedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "contentAvailable": {
                "type": "boolean"
              }
            },
            "required": [
              "receiptId",
              "recipients",
              "receivedAt",
              "contentAvailable"
            ]
          }
        ]
      },
      "Attempt": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deliveryId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "responseCode": {
            "type": [
              "integer",
              "null"
            ]
          },
          "durationMs": {
            "type": [
              "integer",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "deliveryId",
          "status",
          "responseCode",
          "durationMs",
          "error",
          "createdAt",
          "completedAt"
        ]
      },
      "MessageSummary": {
        "type": "object",
        "properties": {
          "receiptId": {
            "type": "string",
            "pattern": "^[a-f0-9]{24}$",
            "description": "Message identifier. Treat it as opaque."
          },
          "sender": {
            "type": [
              "string",
              "null"
            ]
          },
          "recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "messageId": {
            "type": [
              "string",
              "null"
            ]
          },
          "processingStatus": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "parsed",
              "failed",
              "expired"
            ]
          },
          "processingErrorCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "processingError": {
            "type": [
              "string",
              "null"
            ]
          },
          "processingAttemptCount": {
            "type": "integer"
          },
          "processingNextRetryAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "rawBytes": {
            "type": "integer"
          },
          "processedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "contentAvailable": {
            "type": "boolean"
          },
          "rawDownloadUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "threadId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Conversation ID, identical to message.thread_id in webhooks. Null for unavailable metadata or expired content. Treat as opaque."
          }
        },
        "required": [
          "receiptId",
          "sender",
          "recipients",
          "subject",
          "messageId",
          "processingStatus",
          "processingErrorCode",
          "processingError",
          "processingAttemptCount",
          "processingNextRetryAt",
          "receivedAt",
          "expiresAt",
          "rawBytes",
          "processedAt",
          "contentAvailable",
          "rawDownloadUrl",
          "threadId"
        ]
      },
      "Queued": {
        "type": "object",
        "properties": {
          "queued": {
            "type": "boolean"
          },
          "deliveryId": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          }
        },
        "required": [
          "queued",
          "deliveryId",
          "eventId"
        ]
      },
      "Key": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastUsedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "revokedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "name",
          "hint",
          "createdAt",
          "lastUsedAt",
          "revokedAt",
          "scopes"
        ]
      },
      "Billing": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "hasCustomer": {
            "type": "boolean"
          },
          "hasSubscription": {
            "type": "boolean"
          },
          "currentPeriodEnd": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "graceUntil": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cancelAtPeriodEnd": {
            "type": "boolean"
          },
          "lastSyncedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "suspendedDomains": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "plan",
          "status",
          "hasCustomer",
          "hasSubscription",
          "currentPeriodEnd",
          "graceUntil",
          "cancelAtPeriodEnd",
          "lastSyncedAt",
          "suspendedDomains"
        ]
      },
      "Plan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "offered": {
            "type": "boolean"
          },
          "monthlyPriceEur": {
            "type": [
              "number",
              "null"
            ]
          },
          "customDomains": {
            "type": [
              "integer",
              "null"
            ]
          },
          "monthlyMessages": {
            "type": "integer"
          },
          "rawMessageLimitBytes": {
            "type": "integer"
          },
          "retentionDays": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum content retention for this plan. Account settings may select 0 days or any whole number of days from 1 through this maximum."
          },
          "storageLimitBytes": {
            "type": "integer",
            "minimum": 0,
            "description": "Current retained storage capacity in bytes. One GB is 1,000,000,000 bytes."
          },
          "artifactDownloadLimitBytes": {
            "type": "integer",
            "description": "Informational plan value in bytes. It is not an enforced monthly attachment-download limit."
          },
          "perAddressRoutes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          }
        },
        "required": [
          "id",
          "name",
          "offered",
          "monthlyPriceEur",
          "customDomains",
          "monthlyMessages",
          "rawMessageLimitBytes",
          "retentionDays",
          "storageLimitBytes",
          "artifactDownloadLimitBytes",
          "perAddressRoutes"
        ]
      },
      "Delivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deliveryId": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "eventType": {
            "type": "string",
            "const": "email.received"
          },
          "endpointId": {
            "type": "string"
          },
          "endpointName": {
            "type": "string"
          },
          "endpointStatus": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "retrying",
              "delivered",
              "failed"
            ]
          },
          "inProgress": {
            "type": "boolean"
          },
          "responseCode": {
            "type": [
              "integer",
              "null"
            ]
          },
          "durationMs": {
            "type": [
              "integer",
              "null"
            ]
          },
          "attemptCount": {
            "type": "integer"
          },
          "nextRetryAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "deliveryDeadlineAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastError": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "payload": {
            "type": "null"
          },
          "payloadBody": {
            "type": "null"
          },
          "attempts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageAttempt"
            }
          }
        },
        "required": [
          "id",
          "deliveryId",
          "eventId",
          "eventType",
          "endpointId",
          "endpointName",
          "endpointStatus",
          "status",
          "inProgress",
          "responseCode",
          "durationMs",
          "attemptCount",
          "nextRetryAt",
          "deliveryDeadlineAt",
          "lastError",
          "createdAt",
          "payload",
          "payloadBody",
          "attempts"
        ]
      },
      "Usage": {
        "type": "object",
        "properties": {
          "plan": {
            "$ref": "#/components/schemas/Plan"
          },
          "retention": {
            "type": "object",
            "description": "Current account retention policy. Changes apply to existing and newly accepted messages.",
            "properties": {
              "retentionDays": {
                "type": "integer",
                "minimum": 0
              },
              "maxDays": {
                "type": "integer",
                "minimum": 1
              },
              "configuredDays": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0
              }
            },
            "required": [
              "retentionDays",
              "maxDays",
              "configuredDays"
            ]
          },
          "period": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string",
                "format": "date-time"
              },
              "resetsAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "start",
              "resetsAt"
            ]
          },
          "messages": {
            "type": "object",
            "properties": {
              "accepted": {
                "type": "integer"
              },
              "reserved": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              },
              "remaining": {
                "type": "integer"
              },
              "status": {
                "type": "string",
                "enum": [
                  "available",
                  "approaching",
                  "reached"
                ]
              }
            },
            "required": [
              "accepted",
              "reserved",
              "limit",
              "remaining",
              "status"
            ]
          },
          "domains": {
            "type": "object",
            "properties": {
              "used": {
                "type": "integer"
              },
              "limit": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "remaining": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "used",
              "limit",
              "remaining"
            ]
          },
          "addressRoutes": {
            "type": "object",
            "properties": {
              "used": {
                "type": "integer"
              },
              "limit": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "remaining": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "used",
              "limit",
              "remaining"
            ]
          },
          "storage": {
            "$ref": "#/components/schemas/StorageUsage"
          }
        },
        "required": [
          "plan",
          "retention",
          "period",
          "messages",
          "domains",
          "addressRoutes",
          "storage"
        ]
      },
      "MessageDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deliveryId": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "eventType": {
            "type": "string",
            "const": "email.received"
          },
          "endpointId": {
            "type": "string"
          },
          "endpointName": {
            "type": "string"
          },
          "endpointStatus": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "retrying",
              "delivered",
              "failed"
            ]
          },
          "inProgress": {
            "type": "boolean"
          },
          "responseCode": {
            "type": [
              "integer",
              "null"
            ]
          },
          "durationMs": {
            "type": [
              "integer",
              "null"
            ]
          },
          "attemptCount": {
            "type": "integer"
          },
          "nextRetryAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "deliveryDeadlineAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastError": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "payload": {
            "type": "null"
          },
          "payloadBody": {
            "type": "null"
          },
          "attempts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageAttempt"
            }
          }
        },
        "required": [
          "id",
          "deliveryId",
          "eventId",
          "eventType",
          "endpointId",
          "endpointName",
          "endpointStatus",
          "status",
          "inProgress",
          "responseCode",
          "durationMs",
          "attemptCount",
          "nextRetryAt",
          "deliveryDeadlineAt",
          "lastError",
          "createdAt",
          "payload",
          "payloadBody",
          "attempts"
        ]
      },
      "MessageAttempt": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deliveryId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "responseCode": {
            "type": [
              "integer",
              "null"
            ]
          },
          "durationMs": {
            "type": [
              "integer",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "deliveryId",
          "status",
          "responseCode",
          "durationMs",
          "error",
          "createdAt",
          "completedAt"
        ]
      },
      "EndpointDeliverySummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "eventType": {
            "type": "string",
            "const": "email.received"
          },
          "status": {
            "type": "string"
          },
          "responseCode": {
            "type": [
              "integer",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "messageId": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[a-f0-9]{24}$"
          }
        },
        "required": [
          "id",
          "eventId",
          "eventType",
          "status",
          "responseCode",
          "createdAt",
          "messageId"
        ]
      },
      "StorageUsage": {
        "type": "object",
        "properties": {
          "rawBytes": {
            "type": "integer"
          },
          "artifactBytes": {
            "type": "integer"
          },
          "retainedBytes": {
            "type": "integer"
          },
          "reservedBytes": {
            "type": "integer"
          },
          "limitBytes": {
            "type": "integer"
          },
          "remainingBytes": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "available",
              "approaching",
              "reached"
            ]
          }
        },
        "required": [
          "rawBytes",
          "artifactBytes",
          "retainedBytes",
          "reservedBytes",
          "limitBytes",
          "remainingBytes",
          "status"
        ]
      },
      "PayloadFieldNode": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "type": {
            "const": "field"
          },
          "path": {
            "type": "string",
            "maxLength": 1024,
            "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported."
          }
        },
        "required": [
          "type",
          "path"
        ]
      },
      "PayloadObjectNode": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "type": {
            "const": "object"
          },
          "fields": {
            "type": "object",
            "propertyNames": {
              "minLength": 1,
              "maxLength": 128,
              "not": {
                "enum": [
                  "__proto__",
                  "prototype",
                  "constructor"
                ]
              }
            },
            "additionalProperties": {
              "$ref": "#/components/schemas/PayloadMappingNode"
            }
          }
        },
        "required": [
          "type",
          "fields"
        ]
      },
      "PayloadArrayNode": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "type": {
            "const": "array"
          },
          "path": {
            "type": "string",
            "maxLength": 1024,
            "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported."
          },
          "items": {
            "$ref": "#/components/schemas/PayloadMappingNode"
          }
        },
        "required": [
          "type",
          "path",
          "items"
        ]
      },
      "PayloadMappingNode": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/PayloadFieldNode"
          },
          {
            "$ref": "#/components/schemas/PayloadObjectNode"
          },
          {
            "$ref": "#/components/schemas/PayloadArrayNode"
          }
        ]
      },
      "PayloadMapping": {
        "type": "object",
        "additionalProperties": false,
        "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.",
        "properties": {
          "version": {
            "const": 1
          },
          "output": {
            "$ref": "#/components/schemas/PayloadObjectNode"
          }
        },
        "required": [
          "version",
          "output"
        ],
        "example": {
          "version": 1,
          "output": {
            "type": "object",
            "fields": {
              "title": {
                "type": "field",
                "path": "/subject"
              },
              "files": {
                "type": "array",
                "path": "/attachments",
                "items": {
                  "type": "field",
                  "path": "/filename"
                }
              }
            }
          }
        }
      },
      "PayloadMappingError": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "JSON Pointer identifying the invalid field."
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "message"
        ]
      },
      "PayloadPreview": {
        "type": "object",
        "properties": {
          "output": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "body": {
            "type": [
              "string",
              "null"
            ],
            "description": "Exact serialized JSON body, or null when evaluation fails."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PayloadMappingError"
            }
          },
          "missingPaths": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Output JSON Pointers for missing sample values. Missing sources produce null or empty arrays."
          }
        },
        "required": [
          "output",
          "body",
          "errors",
          "missingPaths"
        ]
      },
      "AccountPlan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "maxMessageBytes": {
            "type": "integer"
          },
          "monthlyMessageLimit": {
            "type": "integer"
          },
          "storageLimitBytes": {
            "type": "integer"
          },
          "customDomainLimit": {
            "type": [
              "integer",
              "null"
            ]
          },
          "retentionLimitDays": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "maxMessageBytes",
          "monthlyMessageLimit",
          "storageLimitBytes",
          "customDomainLimit",
          "retentionLimitDays"
        ]
      },
      "AccountBilling": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "paidThrough": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cancelAtPeriodEnd": {
            "type": "boolean"
          }
        },
        "required": [
          "status",
          "paidThrough",
          "cancelAtPeriodEnd"
        ]
      },
      "ThreadSummary": {
        "type": "object",
        "description": "A complete retained thread, or a single retained message without thread metadata.",
        "properties": {
          "threadId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Untranslated conversation ID. Null means the latestMessage stands alone."
          },
          "latestMessage": {
            "$ref": "#/components/schemas/MessageSummary"
          },
          "messageCount": {
            "type": "integer",
            "minimum": 1
          },
          "firstReceivedAt": {
            "type": "string",
            "format": "date-time"
          },
          "latestReceivedAt": {
            "type": "string",
            "format": "date-time"
          },
          "statusCounts": {
            "type": "object",
            "properties": {
              "pending": {
                "type": "integer",
                "minimum": 0
              },
              "processing": {
                "type": "integer",
                "minimum": 0
              },
              "parsed": {
                "type": "integer",
                "minimum": 0
              },
              "failed": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "pending",
              "processing",
              "parsed",
              "failed"
            ],
            "description": "Message counts for the whole retained thread. Each message is counted once."
          }
        },
        "required": [
          "threadId",
          "latestMessage",
          "messageCount",
          "firstReceivedAt",
          "latestReceivedAt",
          "statusCounts"
        ]
      }
    }
  },
  "paths": {
    "/api/account": {
      "get": {
        "summary": "Get account settings",
        "description": "Returns the signed-in user's Wildmail account, current plan and configured message retention.",
        "operationId": "get_api_account",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account settings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object",
                      "additionalProperties": true,
                      "properties": {
                        "userId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "active",
                            "suspended",
                            "disabled"
                          ]
                        },
                        "plan": {
                          "$ref": "#/components/schemas/AccountPlan"
                        },
                        "billing": {
                          "$ref": "#/components/schemas/AccountBilling"
                        },
                        "retentionDays": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    }
                  },
                  "required": [
                    "account"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "A signed-in session is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Account not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update account retention",
        "description": "Sets account retention in whole days. The setting applies to existing and newly received messages. Zero permits at most one self-contained webhook attempt with no retry or replay.",
        "operationId": "put_api_account",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "retentionDays": {
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "required": [
                  "retentionDays"
                ],
                "additionalProperties": false
              },
              "example": {
                "retentionDays": 7
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Retention setting updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object",
                      "properties": {
                        "retentionDays": {
                          "type": "integer",
                          "minimum": 0
                        }
                      },
                      "required": [
                        "retentionDays"
                      ]
                    }
                  },
                  "required": [
                    "account"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Retention must be a whole number within the account plan's maximum.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "A signed-in session is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Account not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Retention could not be synchronized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/delete": {
      "post": {
        "summary": "Delete account",
        "description": "Disables sign-in and inbound mail, cancels an active subscription, schedules removal of retained message content, and deletes account and authentication records. This operation cannot be undone. The request must come from the application origin and include the exact confirmation text.",
        "operationId": "post_api_account_delete",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Must match the configured Wildmail application origin."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirmation": {
                    "type": "string",
                    "const": "DELETE"
                  }
                },
                "required": [
                  "confirmation"
                ],
                "additionalProperties": false
              },
              "example": {
                "confirmation": "DELETE"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deletion completed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "success"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The confirmation value is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "A signed-in session is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Cross-origin request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Deletion is still in progress. Retry the request or contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/{path}": {
      "get": {
        "summary": "Browser authentication action",
        "description": "Browser authentication for the hosted application. Use the Wildmail sign-in and security screens to manage sessions and second-factor challenges. Server integrations use scoped API keys. The path parameter can contain multiple segments. This wildcard is not a literal endpoint.",
        "operationId": "get_api_auth_path",
        "tags": [
          "Authentication"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Library-defined response: JSON, redirect or session-cookie update according to the selected auth endpoint. Schema intentionally unspecified."
          },
          "400": {
            "description": "Authentication validation error."
          },
          "401": {
            "description": "Authentication required."
          },
          "403": {
            "description": "Origin or authorization denied."
          },
          "429": {
            "description": "Authentication rate limit. Shared request limiting can also return 429 rate_limit_exceeded with Retry-After (seconds) and Cache-Control: no-store.",
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying a throttled authentication request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/RequestLimitError"
                    },
                    {
                      "type": "object",
                      "description": "Authentication error returned by the selected sign-in action."
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "auth",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-catch-all": true
      },
      "post": {
        "summary": "Browser authentication action",
        "description": "Browser authentication for the hosted application. Use the Wildmail sign-in and security screens to manage sessions and second-factor challenges. Server integrations use scoped API keys. The path parameter can contain multiple segments. This wildcard is not a literal endpoint.",
        "operationId": "post_api_auth_path",
        "tags": [
          "Authentication"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Library-defined response: JSON, redirect or session-cookie update according to the selected auth endpoint. Schema intentionally unspecified."
          },
          "400": {
            "description": "Authentication validation error."
          },
          "401": {
            "description": "Authentication required."
          },
          "403": {
            "description": "Origin or authorization denied."
          },
          "429": {
            "description": "Authentication rate limit. Shared request limiting can also return 429 rate_limit_exceeded with Retry-After (seconds) and Cache-Control: no-store.",
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying a throttled authentication request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/RequestLimitError"
                    },
                    {
                      "type": "object",
                      "description": "Authentication error returned by the selected sign-in action."
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "auth",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-catch-all": true
      }
    },
    "/api/billing": {
      "get": {
        "summary": "Get billing summary",
        "description": "Browser session only, signed-in account. configured reports whether billing is available.",
        "operationId": "get_api_billing",
        "tags": [
          "Billing"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "billing": {
                      "$ref": "#/components/schemas/Billing"
                    },
                    "configured": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "billing",
                    "configured"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "account missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "Billing unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "session"
      }
    },
    "/api/billing/checkout": {
      "post": {
        "summary": "Create checkout session",
        "description": "Browser session only, signed-in account owner. Origin must exactly match the configured application origin. Creates hosted Stripe Checkout for Starter or Growth.",
        "operationId": "post_api_billing_checkout",
        "tags": [
          "Billing"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "url"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "account missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Existing subscription/conflicting billing operation where applicable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "Billing/provider unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "session",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan": {
                    "type": "string",
                    "enum": [
                      "Starter",
                      "Growth"
                    ]
                  }
                },
                "required": [
                  "plan"
                ]
              }
            }
          }
        }
      }
    },
    "/api/billing/portal": {
      "post": {
        "summary": "Create billing portal session",
        "description": "Browser session only, signed-in account owner. No body. Origin must exactly match the configured application origin. Requires an existing Stripe customer. Returns hosted billing portal URL. Cancellation takes effect at the end of the current billing period. The paid plan continues until then.",
        "operationId": "post_api_billing_portal",
        "tags": [
          "Billing"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "url"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "account missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Existing subscription/conflicting billing operation where applicable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "Billing/provider unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "session"
      }
    },
    "/api/billing/sync": {
      "post": {
        "summary": "Refresh billing state",
        "description": "Browser session only, signed-in account owner. No body. Origin must exactly match the configured application origin. Synchronizes provider state and returns updated summary.",
        "operationId": "post_api_billing_sync",
        "tags": [
          "Billing"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "billing": {
                      "$ref": "#/components/schemas/Billing"
                    }
                  },
                  "required": [
                    "billing"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "account missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Existing subscription/conflicting billing operation where applicable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "Billing/provider unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "session"
      }
    },
    "/api/billing/upgrade": {
      "post": {
        "summary": "Upgrade Starter to Growth",
        "description": "Browser session only, signed-in account owner. No body. Origin must exactly match the configured application origin. Growth applies after confirmation. The prorated difference is included on the next invoice. Usage does not reset. Resolve outstanding payments or scheduled changes first.",
        "operationId": "post_api_billing_upgrade",
        "tags": [
          "Billing"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "billing": {
                      "$ref": "#/components/schemas/Billing"
                    }
                  },
                  "required": [
                    "billing"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "account missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Subscription cannot be changed or has a conflicting operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "Billing/provider unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "session"
      }
    },
    "/api/deliveries": {
      "get": {
        "summary": "List deliveries",
        "description": "Returns the account's delivery history, newest first, 25 per page. Optional status filters narrow the results. Content-free delivery summaries and attempt history remain available after message content expires.",
        "operationId": "get_api_deliveries",
        "tags": [
          "Deliveries"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deliveries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DeliverySummary"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "deliveries",
                    "pagination"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "deliveries:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page."
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "retrying",
                "delivered",
                "failed"
              ]
            }
          }
        ]
      }
    },
    "/api/deliveries/{id}": {
      "get": {
        "summary": "Inspect delivery and attempts",
        "description": "Returns the delivery summary, message availability, and content-free attempt history.",
        "operationId": "get_api_deliveries_id",
        "tags": [
          "Deliveries"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "delivery": {
                      "$ref": "#/components/schemas/Delivery"
                    },
                    "message": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "receiptId": {
                          "type": "string",
                          "pattern": "^[a-f0-9]{24}$"
                        },
                        "receivedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "contentAvailable": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "receiptId",
                        "receivedAt",
                        "expiresAt",
                        "contentAvailable"
                      ]
                    },
                    "contentAvailable": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "delivery",
                    "message",
                    "contentAvailable"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Delivery not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "deliveries:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/deliveries/{id}/replay": {
      "post": {
        "summary": "Replay delivery",
        "description": "Queues a replay using the same event ID and pinned endpoint/shaping revision. Replay requires retained content under the account's current policy, an active endpoint, and no in-progress attempt. Zero-retention deliveries cannot be replayed.",
        "operationId": "post_api_deliveries_id_replay",
        "tags": [
          "Deliveries"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Queued"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Delivery not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Inactive/unconfigured endpoint, unavailable payload or delivery in flight.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Content or replay window expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "deliveries:replay",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/domains": {
      "get": {
        "summary": "List custom domains",
        "description": "Hosted test addresses are excluded. Returns DNS instructions, readiness and the custom-domain allowance.",
        "operationId": "get_api_domains",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domains": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Domain"
                      }
                    },
                    "allowance": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "planName": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "used",
                        "limit",
                        "planName"
                      ]
                    }
                  },
                  "required": [
                    "domains",
                    "allowance"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:read"
      },
      "post": {
        "summary": "Create a custom domain",
        "description": "The authenticated account can create a domain. Domain names normalize to DNS form. Domains reserved for Wildmail service use cannot be added. Configure returned TXT and MX records before verification.",
        "operationId": "post_api_domains",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "$ref": "#/components/schemas/Domain"
                    }
                  },
                  "required": [
                    "domain"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Already claimed or domain_limit_reached. Quota errors include the limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "endpointId": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "domain"
                ]
              },
              "example": {
                "domain": "in.example.com",
                "endpointId": "11111111-1111-4111-8111-111111111111"
              }
            }
          }
        }
      }
    },
    "/api/domains/{id}": {
      "delete": {
        "summary": "Delete custom domain",
        "description": "Signed-in browser session or a scoped API key. Removes a custom domain and refreshes admission routing.",
        "operationId": "delete_api_domains_id",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted. Empty body."
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Domain not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:admin",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "put": {
        "summary": "Set domain destination",
        "description": "Requires endpointId. Set null or an empty string to disconnect. Hosted addresses use /api/hosted-address. Newly accepted messages use the selected destination, while previously accepted messages keep the destination recorded at acceptance.",
        "operationId": "put_api_domains_id",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "$ref": "#/components/schemas/Domain"
                    }
                  },
                  "required": [
                    "domain"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "endpointId": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "endpointId"
                ]
              },
              "example": {
                "endpointId": "11111111-1111-4111-8111-111111111111"
              }
            }
          }
        }
      }
    },
    "/api/domains/{id}/routes": {
      "get": {
        "summary": "List exact-address routes for a custom domain",
        "description": "Lists this domain's exact local-part routes and the account-wide route allowance. UTF-8 local parts are trimmed, Unicode-normalized, and lowercased before matching. Unicode domains use lowercase IDNA ASCII for lookup. Matching is case-insensitive. Plus-tags are preserved literally and are not stripped. Exact matches take precedence over the domain catch-all. A matching exact route can accept mail without a catch-all endpoint. Unmatched addresses are rejected if no catch-all is configured. A suspended exact route or one whose endpoint is unavailable is rejected during SMTP admission instead of falling through to catch-all.",
        "operationId": "get_api_domains_id_routes",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "routes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DomainRoute"
                      }
                    },
                    "allowance": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "limit": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        },
                        "planName": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "used",
                        "limit",
                        "planName"
                      ]
                    }
                  },
                  "required": [
                    "routes",
                    "allowance"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Domain not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      },
      "post": {
        "summary": "Create an exact-address route",
        "description": "Creates an exact local-part route to an endpoint in this account. UTF-8 local parts are trimmed, Unicode-normalized, and lowercased before matching. The maximum is 64 UTF-8 bytes. Free has an allowance of zero and returns 409 route_limit_reached. Recognized non-Free plans have unlimited exact routes. Route status is suspended while the effective plan disallows routes. Stored suspended routes remain counted. Hosted test addresses are managed separately.",
        "operationId": "post_api_domains_id_routes",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "route": {
                      "$ref": "#/components/schemas/DomainRoute"
                    }
                  },
                  "required": [
                    "route"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid local part or endpoint identifier.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Domain or endpoint not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Exact route already exists or the account allowance is exhausted. For Free, code is route_limit_reached and limit is 0.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "localPart": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Plus-tags are preserved literally and are not stripped. Patterns are not supported."
                  },
                  "endpointId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "localPart",
                  "endpointId"
                ]
              },
              "example": {
                "localPart": "orders+acme",
                "endpointId": "11111111-1111-4111-8111-111111111111"
              }
            }
          }
        }
      }
    },
    "/api/domains/{id}/routes/{routeId}": {
      "delete": {
        "summary": "Delete an exact-address route",
        "description": "Removes the exact route so future mail to that address uses the domain catch-all, if configured. Unmatched addresses are rejected when no catch-all is configured. Previously accepted messages retain their pinned route and endpoint revisions.",
        "operationId": "delete_api_domains_id_routes_routeId",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted. Empty body."
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Domain or route not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "routeId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      },
      "put": {
        "summary": "Update an exact-address route",
        "description": "Replaces the route's local part and endpoint for future accepted mail. UTF-8 local parts (at most 64 UTF-8 bytes) are trimmed, Unicode-normalized, and lowercased before matching. Plus-tags are preserved literally and are not stripped. Previously accepted messages retain their pinned route and endpoint revisions.",
        "operationId": "put_api_domains_id_routes_routeId",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "route": {
                      "$ref": "#/components/schemas/DomainRoute"
                    }
                  },
                  "required": [
                    "route"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid local part or endpoint identifier.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Domain, route or endpoint not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The local part is already routed on this domain.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "routeId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "localPart": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Plus-tags are preserved literally and are not stripped. Patterns are not supported."
                  },
                  "endpointId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "localPart",
                  "endpointId"
                ]
              },
              "example": {
                "localPart": "orders+acme",
                "endpointId": "11111111-1111-4111-8111-111111111111"
              }
            }
          }
        }
      }
    },
    "/api/domains/{id}/verify": {
      "post": {
        "summary": "Check domain DNS",
        "description": "No body. Checks ownership TXT and MX separately with an eight-second DNS timeout. A 200 response may have observed.ownership or observed.mx false. domain.ready reports domain catch-all readiness. With no catch-all, a verified domain with valid MX can still accept matching active exact-address routes with active endpoints.",
        "operationId": "post_api_domains_id_verify",
        "tags": [
          "Domains"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "$ref": "#/components/schemas/Domain"
                    },
                    "observed": {
                      "type": "object",
                      "properties": {
                        "ownership": {
                          "type": "boolean"
                        },
                        "mx": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "ownership",
                        "mx"
                      ]
                    }
                  },
                  "required": [
                    "domain",
                    "observed"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Domain not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "DNS lookup unavailable or timed out. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/hosted-address": {
      "get": {
        "summary": "Get hosted test address",
        "description": "A browser session provisions an address if needed. API keys only read an assigned address and receive 404 if none exists. ready means an active endpoint is linked.",
        "operationId": "get_api_hosted_address",
        "tags": [
          "Hosted address"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "address": {
                      "type": "string"
                    },
                    "endpointId": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "endpointName": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "ready": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "address",
                    "endpointId",
                    "endpointName",
                    "ready"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Test address not assigned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:read"
      },
      "put": {
        "summary": "Set hosted address destination",
        "description": "Requires endpointId: a UUID in this account or null to disconnect. Provisions the address if necessary.",
        "operationId": "put_api_hosted_address",
        "tags": [
          "Hosted address"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "domains:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "endpointId": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "endpointId"
                ]
              },
              "example": {
                "endpointId": "11111111-1111-4111-8111-111111111111"
              }
            }
          }
        }
      }
    },
    "/api/keys": {
      "get": {
        "summary": "List API keys and scopes",
        "description": "Browser session only, signed-in account. Lists key metadata and availableScopes. Token secrets are never returned.",
        "operationId": "get_api_keys",
        "tags": [
          "API keys"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keys": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Key"
                      }
                    },
                    "availableScopes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "description"
                        ]
                      }
                    }
                  },
                  "required": [
                    "keys",
                    "availableScopes"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "session"
      },
      "post": {
        "summary": "Create scoped API key",
        "description": "Browser session only, signed-in account. name is 1–80 trimmed characters. scopes is a nonempty unique array of available scope identifiers. token is returned once. Store securely.",
        "operationId": "post_api_keys",
        "tags": [
          "API keys"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "$ref": "#/components/schemas/Key"
                    },
                    "token": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "key",
                    "token"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid name or scope selection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "session",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "uniqueItems": true
                  }
                },
                "required": [
                  "name",
                  "scopes"
                ]
              },
              "example": {
                "name": "Order intake integration",
                "scopes": [
                  "messages:read",
                  "deliveries:read",
                  "deliveries:replay"
                ]
              }
            }
          }
        }
      }
    },
    "/api/keys/{id}": {
      "delete": {
        "summary": "Revoke API key",
        "description": "Browser session only, signed-in account owner. Revokes an active key immediately. An already revoked or missing key returns 404.",
        "operationId": "delete_api_keys_id",
        "tags": [
          "API keys"
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted. Empty body"
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Active API key not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "session",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/messages": {
      "get": {
        "summary": "Search received messages",
        "description": "Returns the account's message history, newest first, 25 per page. Search q matches message ID, event ID, retained sender/recipient, subject and Message-ID. Supported status filters are returned by the API. Expired summaries hide message content.",
        "operationId": "get_api_messages",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "messages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MessageSummary"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "messages",
                    "pagination"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "messages:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive substring search."
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "processing",
                "parsed",
                "failed",
                "expired"
              ]
            }
          }
        ]
      }
    },
    "/api/messages/{id}": {
      "get": {
        "summary": "Inspect received message",
        "description": "Returns a message summary, parsed message details while content is available, and its delivery summaries. The message ID is the 24-character receiptId from GET /api/messages. Message content and attachments follow the account's current retention policy.",
        "operationId": "get_api_messages_id",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/MessageSummary"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "processedAt": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "contentAvailable": {
                              "type": "boolean"
                            },
                            "rawDownloadUrl": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          },
                          "required": [
                            "processedAt",
                            "contentAvailable",
                            "rawDownloadUrl"
                          ]
                        }
                      ]
                    },
                    "deliveries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MessageDelivery"
                      }
                    },
                    "details": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "additionalProperties": true,
                      "description": "Parsed message details, or null when content is unavailable."
                    }
                  },
                  "required": [
                    "message",
                    "details",
                    "deliveries"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Message not found or outside this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "messages:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ]
      }
    },
    "/api/messages/{id}/attachments/{attachmentId}": {
      "get": {
        "summary": "Download a retained attachment",
        "description": "Streams a retained attachment while the account's current retention policy permits access. Requires the account's messages:read scope or a signed-in session. The response uses a safe Content-Disposition filename and private, no-store caching.",
        "operationId": "get_api_messages_id_attachments_attachmentId",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "x-audience": "management",
        "x-required-scope": "messages:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            },
            "description": "Opaque message ID returned as receiptId by the message API."
          },
          {
            "name": "attachmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Attachment ID from the message details."
          }
        ],
        "responses": {
          "200": {
            "description": "Attachment bytes.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required API key scope is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Message or attachment not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Attachment content is no longer available under the current retention policy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        }
      }
    },
    "/api/messages/{id}/preview": {
      "get": {
        "summary": "Preview message body",
        "description": "Returns a sanitized text or HTML preview of a retained message. Access follows the account's current retention policy.",
        "operationId": "get_api_messages_id_preview",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Content/body not available (may be empty).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 2 MiB preview limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "Storage unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "management",
        "x-required-scope": "messages:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "text",
                "html"
              ],
              "default": "text"
            }
          }
        ]
      }
    },
    "/api/messages/{id}/raw": {
      "get": {
        "summary": "Download raw MIME",
        "description": "Streams the retained RFC 822 email with private, no-store caching. Access follows the account's current retention policy.",
        "operationId": "get_api_messages_id_raw",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "message/rfc822": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Message unavailable or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Message content is no longer available under the current retention policy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "Message storage temporarily unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "management",
        "x-required-scope": "messages:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/usage": {
      "get": {
        "summary": "Get account usage",
        "description": "Returns the account plan, UTC-month accepted-message allowance, custom domains, exact-address routes, storage quota and current retention setting.",
        "operationId": "get_api_usage",
        "tags": [
          "Usage"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "usage": {
                      "$ref": "#/components/schemas/Usage"
                    }
                  },
                  "required": [
                    "usage"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Account not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "usage:read"
      }
    },
    "/api/webhooks": {
      "get": {
        "summary": "List webhook endpoints",
        "description": "Returns public endpoint metadata. Signing secrets are never returned by reads.",
        "operationId": "get_api_webhooks",
        "tags": [
          "Webhook endpoints"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoints": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Endpoint"
                      }
                    }
                  },
                  "required": [
                    "endpoints"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "webhooks:read"
      },
      "post": {
        "summary": "Create webhook endpoint",
        "description": "name is trimmed (1–80 characters). Description is at most 300 characters. Destinations require public HTTPS on port 443 and pass DNS/address checks. Save signingSecret now: it is returned once. Optional payloadMapping shapes the complete body. Omit it or use null for the standard body.",
        "operationId": "post_api_webhooks",
        "tags": [
          "Webhook endpoints"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint": {
                      "$ref": "#/components/schemas/Endpoint"
                    },
                    "signingSecret": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "endpoint",
                    "signingSecret"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid fields or unsafe destination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "500": {
            "description": "Creation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Webhook secret encryption unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "management",
        "x-required-scope": "webhooks:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 300
                  },
                  "payloadMapping": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/PayloadMapping"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "One optional mapping per endpoint. Null uses the standard webhook body. Mapping changes apply only to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body."
                  }
                },
                "required": [
                  "name",
                  "url"
                ]
              },
              "example": {
                "name": "Order intake",
                "url": "https://api.example.com/email",
                "description": "Incoming purchase orders"
              }
            }
          }
        }
      }
    },
    "/api/webhooks/{id}": {
      "delete": {
        "summary": "Delete webhook endpoint",
        "description": "Signed-in browser session or scoped API key. Refreshes affected domain routing. Related delivery history is removed with the endpoint.",
        "operationId": "delete_api_webhooks_id",
        "tags": [
          "Webhook endpoints"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted. Empty body"
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "webhooks:admin",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "get": {
        "summary": "Inspect webhook endpoint",
        "description": "Returns the account's endpoint and its content-free delivery summaries, 10 per page. API keys also need deliveries:read to see delivery history. Otherwise deliveries is [] and pagination is null.",
        "operationId": "get_api_webhooks_id",
        "tags": [
          "Webhook endpoints"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint": {
                      "$ref": "#/components/schemas/Endpoint"
                    },
                    "deliveries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EndpointDeliverySummary"
                      }
                    },
                    "pagination": {
                      "anyOf": [
                        {
                          "$ref": "#/components/schemas/Pagination"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "endpoint",
                    "deliveries",
                    "pagination"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "webhooks:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page."
          }
        ]
      },
      "post": {
        "summary": "Rotate webhook signing secret",
        "description": "Rotates the endpoint signing secret. The new secret is returned once. Accepted messages continue to use their pinned signing-key version.",
        "operationId": "post_api_webhooks_id",
        "tags": [
          "Webhook endpoints"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint": {
                      "$ref": "#/components/schemas/Endpoint"
                    },
                    "signingSecret": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "endpoint",
                    "signingSecret"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "description": "Secret encryption unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "Request limiter responses use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-audience": "management",
        "x-required-scope": "webhooks:admin",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "put": {
        "summary": "Update webhook endpoint",
        "description": "Updates any supplied endpoint fields: name, URL, description, status, and payload mapping. Newly accepted messages pin the endpoint destination and shaping revision. Pending deliveries keep those pinned revisions. Pausing an endpoint stops sends.",
        "operationId": "put_api_webhooks_id",
        "tags": [
          "Webhook endpoints"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint": {
                      "$ref": "#/components/schemas/Endpoint"
                    }
                  },
                  "required": [
                    "endpoint"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 300
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "paused"
                    ]
                  },
                  "payloadMapping": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/PayloadMapping"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "One optional mapping per endpoint. Null uses the standard webhook body. Mapping changes apply only to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body."
                  }
                },
                "required": []
              },
              "example": {
                "status": "paused"
              }
            }
          }
        }
      }
    },
    "/api/webhooks/{id}/preview": {
      "post": {
        "summary": "Preview a draft webhook payload mapping",
        "description": "Evaluates a draft against a supplied sample object without saving or sending. Endpoint must belong to the authenticated account. Null mapping returns the standard body. Missing optional fields are reported in missingPaths, separate from validation errors.",
        "operationId": "post_api_webhooks_id_preview",
        "tags": [
          "Webhook endpoints"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payloadMapping": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/PayloadMapping"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "One optional mapping per endpoint. Null uses the standard webhook body. Mapping changes apply only to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body."
                  },
                  "sample": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Sample webhook object. May omit optional fields to inspect missing-value behavior."
                  }
                },
                "required": [
                  "payloadMapping",
                  "sample"
                ]
              },
              "example": {
                "payloadMapping": {
                  "version": 1,
                  "output": {
                    "type": "object",
                    "fields": {
                      "title": {
                        "type": "field",
                        "path": "/subject"
                      }
                    }
                  }
                },
                "sample": {
                  "subject": "Purchase order PO-8812"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful preview output and exact body. The errors array is empty. Missing source values are reported separately in missingPaths.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayloadPreview"
                }
              }
            }
          },
          "400": {
            "description": "Malformed input, invalid mapping, or evaluation failure. Mapping errors include field-level errors with path and message. Evaluation failures return null output and body.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "$ref": "#/components/schemas/PayloadPreview"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint not found in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "webhooks:read"
      }
    },
    "/api/webhooks/{id}/test": {
      "post": {
        "summary": "Queue a test webhook",
        "description": "No body. Endpoint must be active with a saved revision and signing secret. Asynchronously queues a test payload with type: email.test, schema_version: 2026-09-01, and a 24-hour deadline. It is not a parsed email.received payload. Applies the saved payload mapping, which can omit these fields. A 202 response confirms scheduling. Inspect the delivery to determine success.",
        "operationId": "post_api_webhooks_id_test",
        "tags": [
          "Webhook endpoints"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Queued"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Endpoint paused or not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/threads": {
      "get": {
        "summary": "List retained threads",
        "description": "Lists account-scoped retained conversations, 25 groups per page, sorted by latest receipt descending with a stable ID tie-breaker. q and status match a retained member, including older members. Counts and latestMessage describe the complete retained thread. Search is a literal case-insensitive substring across sender, routed recipient, subject, Message-ID, receipt ID, event ID and thread ID. Combined filters must match the same member. Unthreaded messages appear individually with threadId null. Zero-day retention returns an empty list. Expired delivery audits are accessible through individual messages, not threads.",
        "operationId": "get_api_threads",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "threads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ThreadSummary"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "retentionDays": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "minimum": 0
                    }
                  },
                  "required": [
                    "threads",
                    "pagination",
                    "retentionDays"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "messages:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Pages start at 1. Invalid input becomes 1. Pages beyond the result set are empty."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive substring search."
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "processing",
                "parsed",
                "failed",
                "expired"
              ]
            },
            "description": "Match any retained member with this message status. parsed means complete. expired returns no threads."
          }
        ]
      }
    },
    "/api/threads/{id}": {
      "get": {
        "summary": "Inspect a retained thread",
        "description": "Returns the complete retained thread summary and its message summaries, oldest receipt first with a stable message ID tie-breaker, 25 messages per page. Current retention applies to both counts and members. Unknown, foreign-account, fully expired and zero-day threads return 404. IDs are the threadId values from message and thread summaries. Each message links to existing preview, raw download, attachment and delivery APIs.",
        "operationId": "get_api_threads_id",
        "tags": [
          "Threads"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "thread": {
                      "$ref": "#/components/schemas/ThreadSummary"
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MessageSummary"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "thread",
                    "messages",
                    "pagination"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or account access missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Thread not found, outside this account, or without retained messages.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RequestRateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/RequestRateLimitUnavailable"
          }
        },
        "x-audience": "management",
        "x-required-scope": "messages:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Pages start at 1. Invalid input becomes 1. Pages beyond the result set are empty."
          }
        ]
      }
    }
  },
  "tags": [
    {
      "name": "Account",
      "description": "Read account status and manage message retention or account deletion."
    },
    {
      "name": "Domains",
      "description": "Verify custom domains and assign their receiving destinations."
    },
    {
      "name": "Hosted address",
      "description": "Connect a hosted test address before changing DNS."
    },
    {
      "name": "Webhook endpoints",
      "description": "Manage endpoint destinations, signing secrets and test events."
    },
    {
      "name": "Deliveries",
      "description": "Inspect delivery attempts and replay eligible retained messages."
    },
    {
      "name": "Messages",
      "description": "Search, inspect, and download retained messages and attachments."
    },
    {
      "name": "Usage",
      "description": "Inspect account plan, monthly message allowance, mailbox quota, and retention."
    },
    {
      "name": "API keys",
      "description": "Manage scoped credentials for one individual Wildmail account."
    },
    {
      "name": "Billing",
      "description": "Manage billing for one individual Wildmail account."
    },
    {
      "name": "Authentication",
      "description": "Account sign-in and security through the hosted application."
    },
    {
      "name": "Threads",
      "description": "Browse retained conversations and their chronological messages."
    }
  ]
}
