{
    "openapi": "3.1.0",
    "info": {
        "title": "Mailyte API",
        "version": "v1",
        "description": "The Mailyte API lets your own software do everything you can do in the Mailyte\ndashboard and webmail: send mail, manage domains and mailboxes, read delivery\nevents, run campaigns, and receive webhooks.\n\nThere are two credentials, because there are two kinds of caller.\n\nAn **organization API key** (`mk_live_\u2026`) belongs to an organization and acts on\nits behalf \u2014 this is what your application uses. A **mailbox token** belongs to\none mailbox and acts as that person, and is what the Mailbox API takes.\n\nEvery response from the organization API is wrapped in the same envelope:\n\n```json\n{ \"message\": \"\u2026\", \"data\": { }, \"success\": true, \"code\": 200 }\n```\n\n`data` holds the result. `success` and `code` restate the HTTP status so a client\nthat only reads the body can still tell what happened.",
        "contact": {
            "name": "Mailyte support",
            "url": "https://mailyte.com/contact-sales"
        },
        "license": {
            "name": "Proprietary"
        }
    },
    "servers": [
        {
            "url": "https://app.mailyte.com",
            "description": "Production"
        },
        {
            "url": "{host}",
            "description": "A self-hosted installation",
            "variables": {
                "host": {
                    "default": "https://app.example.com",
                    "description": "Your own Mailyte host"
                }
            }
        }
    ],
    "tags": [
        {
            "name": "Sending",
            "description": "Submit messages for delivery, individually or in batches."
        },
        {
            "name": "Templates",
            "description": "Stored templates with variables, rendered at send time."
        },
        {
            "name": "Domains",
            "description": "Add a sending domain, publish its DNS, and verify it."
        },
        {
            "name": "Mailboxes",
            "description": "Provision mailboxes, aliases and forwarding for a domain."
        },
        {
            "name": "Senders",
            "description": "Verified identities a message may be sent as."
        },
        {
            "name": "SMTP credentials",
            "description": "Logins for applications that relay over SMTP rather than HTTP."
        },
        {
            "name": "Events",
            "description": "What happened to a message after you submitted it."
        },
        {
            "name": "Suppressions",
            "description": "Addresses Mailyte will refuse to send to, and why."
        },
        {
            "name": "Verification",
            "description": "Check whether addresses exist before you send, without sending anything."
        },
        {
            "name": "Webhooks",
            "description": "Receive delivery events at your own endpoint as they happen."
        },
        {
            "name": "Sandbox",
            "description": "Test inboxes that catch mail instead of delivering it: over SMTP, or from a test-mode API key."
        },
        {
            "name": "Contacts",
            "description": "Contacts, lists, custom fields and segments."
        },
        {
            "name": "Campaigns",
            "description": "Bulk sends to a list or segment, scheduled and reported on."
        },
        {
            "name": "Automations",
            "description": "Journeys that run per contact: triggered by a list, a tag or an event your system records, with waits and emails in between."
        },
        {
            "name": "Reports",
            "description": "Deliverability, engagement and volume reporting."
        },
        {
            "name": "Transport rules",
            "description": "Organization-wide rules applied to mail in transit."
        },
        {
            "name": "Account",
            "description": "Organization usage, limits, API keys and dedicated IPs."
        },
        {
            "name": "Mailbox API",
            "description": "Everything the webmail does, for one mailbox. Takes a mailbox token, not an organization API key."
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "An organization API key, created on the Developer page. Send it as `Authorization: Bearer mk_live_\u2026`. The key names its own organization, so no `X-Organization-ID` header is needed. A test key (`mk_test_\u2026`) works the same way, but its sends go to your Sandbox and are never delivered."
            },
            "SessionToken": {
                "type": "http",
                "scheme": "bearer",
                "description": "A signed-in user token, used by first-party applications. Requires an `X-Organization-ID` header naming the organization to act in."
            },
            "MailboxToken": {
                "type": "http",
                "scheme": "bearer",
                "description": "A mailbox token from POST /api/v1/mailbox-auth/login. Acts as one mailbox holder, not as the organization."
            }
        },
        "schemas": {
            "Envelope": {
                "type": "object",
                "description": "Every organization API response has this shape. `data` holds the result.",
                "required": [
                    "message",
                    "success",
                    "code"
                ],
                "properties": {
                    "message": {
                        "type": "string",
                        "description": "Human-readable summary of what happened."
                    },
                    "data": {
                        "description": "The result. Shape depends on the endpoint; null on most errors."
                    },
                    "success": {
                        "type": "boolean"
                    },
                    "code": {
                        "type": "integer",
                        "description": "Repeats the HTTP status code."
                    }
                }
            },
            "MailboxEnvelope": {
                "type": "object",
                "description": "Every Mailbox API response has this shape, which differs from the organization API's: `{type, msg, data}`. `type` is `success` or `error` (there is no `success` boolean and no `code`; read the HTTP status). Check `type` before reading `data`, and expect `data` to be missing when a call returns nothing.",
                "required": [
                    "type",
                    "msg"
                ],
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "success",
                            "error"
                        ],
                        "description": "Whether the call succeeded."
                    },
                    "msg": {
                        "type": "string",
                        "description": "Human-readable summary of what happened."
                    },
                    "data": {
                        "description": "The result. Shape depends on the endpoint; absent when there is none."
                    },
                    "error_code": {
                        "type": "string",
                        "description": "A stable identifier for the subset of failures worth branching on, such as `insights_busy`. Present on some errors only."
                    }
                }
            },
            "Scope": {
                "type": "string",
                "enum": [
                    "messages:send",
                    "templates:read",
                    "templates:write",
                    "domains:read",
                    "domains:write",
                    "mailboxes:read",
                    "mailboxes:write",
                    "senders:read",
                    "senders:write",
                    "smtp:read",
                    "smtp:write",
                    "events:read",
                    "reports:read",
                    "suppressions:read",
                    "suppressions:write",
                    "webhooks:read",
                    "webhooks:write",
                    "contacts:read",
                    "contacts:write",
                    "campaigns:read",
                    "campaigns:write",
                    "transport_rules:read",
                    "transport_rules:write",
                    "account:read",
                    "automations:read",
                    "automations:write",
                    "contact_events:write",
                    "sandbox:read",
                    "sandbox:write",
                    "verification:read",
                    "verification:write"
                ]
            },
            "PaginationMeta": {
                "type": "object",
                "description": "Pagination state for a list response. The page links reflect the parameters you sent and nothing Mailyte added on the way through.",
                "properties": {
                    "current_page": {
                        "type": "integer"
                    },
                    "per_page": {
                        "type": "integer"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "last_page": {
                        "type": "integer"
                    },
                    "from": {
                        "type": "integer",
                        "nullable": true
                    },
                    "to": {
                        "type": "integer",
                        "nullable": true
                    },
                    "first_page_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "last_page_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "next_page_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "prev_page_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "path": {
                        "type": "string"
                    },
                    "can_load_more": {
                        "type": "boolean"
                    }
                }
            },
            "HTTPValidationError": {
                "properties": {
                    "detail": {
                        "items": {
                            "$ref": "#/components/schemas/ValidationError"
                        },
                        "type": "array",
                        "title": "Detail"
                    }
                },
                "type": "object",
                "title": "HTTPValidationError"
            },
            "ClassifyItem": {
                "properties": {
                    "id": {
                        "type": "string",
                        "maxLength": 300,
                        "minLength": 1,
                        "title": "Id"
                    },
                    "subject": {
                        "type": "string",
                        "maxLength": 1000,
                        "title": "Subject",
                        "default": ""
                    },
                    "preview": {
                        "type": "string",
                        "maxLength": 2000,
                        "title": "Preview",
                        "default": ""
                    }
                },
                "type": "object",
                "required": [
                    "id"
                ],
                "title": "ClassifyItem"
            },
            "ErrorResponse": {
                "properties": {
                    "type": {
                        "type": "string",
                        "title": "Type",
                        "default": "error"
                    },
                    "msg": {
                        "type": "string",
                        "title": "Msg"
                    },
                    "error_code": {
                        "anyOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Error Code"
                    },
                    "correlation_id": {
                        "anyOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Correlation Id"
                    }
                },
                "type": "object",
                "required": [
                    "msg"
                ],
                "title": "ErrorResponse",
                "description": "Shape of every non-2xx JSON body (create_api_response('error', ...))."
            },
            "EmailInput": {
                "properties": {
                    "address": {
                        "type": "string",
                        "maxLength": 320,
                        "title": "Address"
                    },
                    "type": {
                        "anyOf": [
                            {
                                "type": "string",
                                "maxLength": 20
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Type"
                    }
                },
                "type": "object",
                "required": [
                    "address"
                ],
                "title": "EmailInput"
            },
            "PhoneInput": {
                "properties": {
                    "number": {
                        "type": "string",
                        "maxLength": 50,
                        "title": "Number"
                    },
                    "type": {
                        "anyOf": [
                            {
                                "type": "string",
                                "maxLength": 20
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Type"
                    }
                },
                "type": "object",
                "required": [
                    "number"
                ],
                "title": "PhoneInput"
            },
            "ValidationError": {
                "properties": {
                    "loc": {
                        "items": {
                            "anyOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "integer"
                                }
                            ]
                        },
                        "type": "array",
                        "title": "Location"
                    },
                    "msg": {
                        "type": "string",
                        "title": "Message"
                    },
                    "type": {
                        "type": "string",
                        "title": "Error Type"
                    },
                    "input": {
                        "title": "Input"
                    },
                    "ctx": {
                        "type": "object",
                        "title": "Context"
                    }
                },
                "type": "object",
                "required": [
                    "loc",
                    "msg",
                    "type"
                ],
                "title": "ValidationError"
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Envelope"
                        },
                        "example": {
                            "message": "Invalid API key.",
                            "data": null,
                            "success": false,
                            "code": 401
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Envelope"
                        },
                        "example": {
                            "message": "This API key is missing the required scope: messages:send.",
                            "data": null,
                            "success": false,
                            "code": 403
                        }
                    }
                }
            },
            "NotFound": {
                "description": "No such resource in this organization.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Envelope"
                        },
                        "example": {
                            "message": "Not found.",
                            "data": null,
                            "success": false,
                            "code": 404
                        }
                    }
                }
            },
            "ValidationFailed": {
                "description": "The request was understood but the values were not acceptable.",
                "content": {
                    "application/json": {
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "errors": {
                                            "type": "object",
                                            "additionalProperties": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        },
                        "example": {
                            "message": "Validation failed",
                            "code": 422,
                            "success": false,
                            "errors": {
                                "to": [
                                    "The to field must be a valid email address."
                                ]
                            }
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.",
                "headers": {
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Seconds to wait before retrying."
                    },
                    "X-RateLimit-Limit": {
                        "schema": {
                            "type": "integer"
                        }
                    },
                    "X-RateLimit-Remaining": {
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Envelope"
                        },
                        "example": {
                            "message": "Sending rate limit exceeded.",
                            "data": null,
                            "success": false,
                            "code": 429
                        }
                    }
                }
            }
        }
    },
    "security": [
        {
            "ApiKeyAuth": []
        }
    ],
    "paths": {
        "/api/v1/messages": {
            "post": {
                "operationId": "postMessages",
                "summary": "Send a message",
                "tags": [
                    "Sending"
                ],
                "x-required-scope": "messages:send",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "description": "Makes this request safe to retry. Use `<app>-<ULID>`, such as `crm-01JBT8XQ2M9WYC3K4F6R7S8T9V`; any other shape is a 422. Send the same key on every retry: a repeat gets the first answer with `Idempotency-Replayed: true`, a key reused for a different request is a 422, and one still running is a 409 with `Retry-After`. Keys last 24 hours, per organization.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z][a-z0-9]{0,19}-[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
                            "example": "crm-01JBT8XQ2M9WYC3K4F6R7S8T9V"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The message was accepted for delivery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "message"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Mailyte's ID for this message: a ULID such as `01JBT8XQ2M9WYC3K4F6R7S8T9V`, without angle brackets. Look it up right away with `GET /email-logs/messages/{id}`. It is not the Message-ID header."
                                                        },
                                                        "message_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Message-ID header as sent, angle brackets included, such as `<01JBT8XQ2M\u2026@example.com>`. Use it, percent-encoded, with `GET /domains/{domain}/messages/{messageId}`. It is not the same as `id`."
                                                        },
                                                        "recipient": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The first recipient's address, without a display name. Read `recipients` for everyone the message was sent to."
                                                        },
                                                        "recipients": {
                                                            "type": "object",
                                                            "description": "Everyone the message was addressed to. Bcc recipients are never listed here; they appear only in your delivery log.",
                                                            "properties": {
                                                                "to": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "As accepted, including any display name."
                                                                },
                                                                "cc": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Empty when there were no cc recipients."
                                                                },
                                                                "count": {
                                                                    "type": "integer",
                                                                    "description": "To plus Cc. Excludes Bcc, which is not published here; the limit of 50 counts all three together."
                                                                }
                                                            }
                                                        },
                                                        "reply_to": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Reply-To address sent. Null when none was set; replies then go to `from`."
                                                        },
                                                        "attachment_count": {
                                                            "type": "integer",
                                                            "description": "How many files were attached."
                                                        },
                                                        "from": {
                                                            "type": "object",
                                                            "description": "The sender. An object here, and everywhere else a sender appears, so one piece of caller code reads all of them.",
                                                            "properties": {
                                                                "email": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The address the message was sent from."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The display name in the `From:` header. Null when the sender has no display name, so the message went out as a bare address."
                                                                }
                                                            }
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The subject as sent, with `{{ }}` variables filled in. An empty subject is `\"\"`, never null."
                                                        },
                                                        "submitted_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When we accepted the message. This is not delivery: a 200 means queued, and the outcome arrives as a delivery event or a webhook."
                                                        },
                                                        "mode": {
                                                            "type": "string",
                                                            "enum": [
                                                                "live",
                                                                "test"
                                                            ],
                                                            "description": "`live` for a real send. `test` when the request used a test API key (`mk_test_\u2026`): the message was checked and built like a real one, then stored in your Sandbox instead of being delivered. Read it with `GET /sandbox/messages/{id}`. Test sends skip suppression and rate limits, and fire no live webhooks."
                                                        },
                                                        "sandbox": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Where a test send was stored. Null for a live send.",
                                                            "properties": {
                                                                "message_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sandbox message id, for `GET /sandbox/messages/{id}`. Not the same as `id`: that is the Message-ID local part the message carries, this is the sandbox's own record of it."
                                                                },
                                                                "inbox_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The inbox it landed in: your default sandbox inbox, created for you on the first test send if you had none."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "message": "Message submitted successfully",
                                    "code": 200,
                                    "success": true,
                                    "data": {
                                        "message_id": "<01JBT8XQ2M@yourdomain.com>",
                                        "event_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                        "to": "ada@example.com",
                                        "from": "hello@yourdomain.com",
                                        "subject": "Your receipt from Acme",
                                        "submitted_at": "2026-09-17T10:04:11.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Submits one message for delivery and returns as soon as it is accepted \u2014 delivery\nitself happens asynchronously, so a `200` here means \"queued\", not \"in their inbox\".\nWatch for the outcome through [delivery events](/developer/guides/handling-delivery-events)\nor a webhook.\n\nThree things have to be true before a send will work, and they are the cause of\nalmost every first-attempt failure:\n\n1. **The domain in `from` is verified.** See [Managing domains and DNS](/developer/guides/domains-and-dns).\n2. **`from` is a verified sender** belonging to your organization. An address that\n   merely sits on a verified domain is not enough; it has to exist as a sender.\n3. **The recipient is not suppressed.** Mailyte refuses sends to addresses that have\n   bounced, complained or unsubscribed, and it refuses them *before* your own list\n   logic gets a say. A suppressed recipient returns `422` and records an\n   `email.dropped` event.\n\nProvide content either directly (`subject` plus `html` and/or `text`) or by naming a\n`template_id`. If you do both, the fields you pass win over the template's.\n`variables` are substituted in either case.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "to",
                                    "from"
                                ],
                                "properties": {
                                    "to": {
                                        "oneOf": [
                                            {
                                                "type": "string"
                                            },
                                            {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                }
                                            }
                                        ],
                                        "description": "Recipients: one address or a list, each `user@example.com` or `Name <user@example.com>`. At most 50 across `to`, `cc` and `bcc` together. Use `/messages/batch` for more, or when each recipient needs their own values."
                                    },
                                    "from": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Must be a verified sender in your organization. The display name comes from the sender record."
                                    },
                                    "cc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Carbon-copy recipients. Counts toward the same 50."
                                    },
                                    "bcc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Blind-copy recipients, counted in the same 50. No recipient can see them, and they are not listed in the response."
                                    },
                                    "reply_to": {
                                        "type": "string",
                                        "description": "Where replies go instead of `from`. Accepts a display name."
                                    },
                                    "headers": {
                                        "type": "object",
                                        "additionalProperties": {
                                            "type": "string"
                                        },
                                        "description": "Custom headers, at most 25, such as `In-Reply-To` and `References` to thread a conversation. Headers Mailyte sets itself (From, To, Subject, Message-ID, DKIM-Signature, List-Unsubscribe, Bcc, X-Mailyte-*) are refused with a 422."
                                    },
                                    "attachments": {
                                        "type": "array",
                                        "description": "Files to attach. The whole message may be at most 10 MB, measured AFTER base64 encoding \u2014 the encoding inflates by roughly a third, so budget accordingly. Windows executable and script extensions are refused.",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "name",
                                                "content"
                                            ],
                                            "properties": {
                                                "name": {
                                                    "type": "string",
                                                    "description": "Filename as the recipient sees it. Its extension is checked against the blocked list.",
                                                    "x-example": "Spring newsletter"
                                                },
                                                "content": {
                                                    "type": "string",
                                                    "format": "byte",
                                                    "description": "The file, base64 encoded.",
                                                    "x-example": {
                                                        "headline": "Our October update"
                                                    }
                                                },
                                                "content_type": {
                                                    "type": "string",
                                                    "description": "MIME type. Guessed from the filename when omitted."
                                                },
                                                "content_id": {
                                                    "type": "string",
                                                    "description": "Set this to show the file inline instead of attaching it, and use it in your HTML as `<img src=\"cid:THE_VALUE\">`."
                                                }
                                            }
                                        }
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "description": "Required unless template_id is given.",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "type": "string",
                                        "description": "HTML body. Required unless template_id or text is given.",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    },
                                    "text": {
                                        "type": "string",
                                        "description": "Plain-text body. Always worth sending alongside html.",
                                        "x-example": "Hi {{name}}, here is what is new this month."
                                    },
                                    "template_id": {
                                        "type": "string",
                                        "description": "A stored template to render instead of inline content.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "variables": {
                                        "type": "object",
                                        "description": "Values for `{{ name }}` placeholders in the subject, HTML and text, such as `{{ first_name | default('there') }}`. Values are HTML-escaped in the HTML body. Mailchimp merge tags such as `*|FNAME|*` work too.",
                                        "additionalProperties": true
                                    },
                                    "metadata": {
                                        "type": "object",
                                        "additionalProperties": {
                                            "type": "string"
                                        },
                                        "description": "Your own data, returned on every delivery event for this message and never shown in it, such as your order ID. At most 10 fields; keys up to 20 characters, values up to 80."
                                    },
                                    "tags": {
                                        "type": "array",
                                        "maxItems": 10,
                                        "items": {
                                            "type": "string",
                                            "maxLength": 64
                                        },
                                        "description": "Your own labels, returned on the delivery events for this message. At most 10."
                                    },
                                    "tracking": {
                                        "type": "boolean",
                                        "description": "Open and click tracking for this message. Left out, it is off for application mail and on for `stream: marketing`. Untracked links stay exactly as you wrote them."
                                    },
                                    "stream": {
                                        "type": "string",
                                        "enum": [
                                            "marketing"
                                        ],
                                        "description": "Send over the marketing egress IP instead of the transactional one. Omit for application mail.",
                                        "x-example": "transactional"
                                    }
                                }
                            },
                            "example": {
                                "to": [
                                    "Ada Lovelace <ada@example.com>"
                                ],
                                "cc": [
                                    "accounts@acme.com"
                                ],
                                "from": "hello@yourdomain.com",
                                "reply_to": "support@yourdomain.com",
                                "subject": "Your receipt from Acme",
                                "html": "<h1>Thanks, {{first_name}}</h1><p>Your order is on its way.</p>",
                                "text": "Thanks, {{first_name}}\nYour order is on its way.",
                                "variables": {
                                    "first_name": "Ada"
                                },
                                "tags": [
                                    "receipt"
                                ],
                                "headers": {
                                    "X-Order-Id": "ord_1234"
                                },
                                "metadata": {
                                    "order_id": "ord_1234",
                                    "tier": "pro"
                                },
                                "attachments": [
                                    {
                                        "name": "invoice.pdf",
                                        "content": "JVBERi0xLjQKJ...",
                                        "content_type": "application/pdf"
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/messages/batch": {
            "post": {
                "operationId": "postMessagesBatch",
                "summary": "Send a batch of messages",
                "tags": [
                    "Sending"
                ],
                "x-required-scope": "messages:send",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "description": "Makes this request safe to retry. Use `<app>-<ULID>`, such as `crm-01JBT8XQ2M9WYC3K4F6R7S8T9V`; any other shape is a 422. Send the same key on every retry: a repeat gets the first answer with `Idempotency-Replayed: true`, a key reused for a different request is a 422, and one still running is a 409 with `Retry-After`. Keys last 24 hours, per organization.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z][a-z0-9]{0,19}-[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
                            "example": "crm-01JBT8XQ2M9WYC3K4F6R7S8T9V"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The batch was processed. Individual recipients may still have failed \u2014 check `failed`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "batch"
                                                            ]
                                                        },
                                                        "sent": {
                                                            "type": "integer",
                                                            "description": "Rows where `accepted` is true."
                                                        },
                                                        "failed": {
                                                            "type": "integer",
                                                            "description": "Rows where `accepted` is false. A refused recipient is a row, never a failed request: `sent + failed` always equals `results` length."
                                                        },
                                                        "results": {
                                                            "type": "array",
                                                            "description": "One row per recipient, in the order submitted.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "recipient": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The recipient this row is about, as you sent it."
                                                                    },
                                                                    "accepted": {
                                                                        "type": "boolean",
                                                                        "description": "The ONLY field to branch on. Every row carries every key, so a missing `id` never has to be read as a success."
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Mailyte's ID for this recipient's copy, like `id` on `POST /messages`. Null when `accepted` is false."
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The RFC 5322 Message-ID for this recipient's copy, angle brackets included, for `GET /domains/{domain}/messages/{messageId}`. A different string from `id`, for a different endpoint. Null when `accepted` is false."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why this recipient was refused, such as a suppressed or malformed address. Null when `accepted` is true."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "message": "Batch processed",
                                    "code": 200,
                                    "success": true,
                                    "data": {
                                        "sent": 1,
                                        "failed": 1,
                                        "results": [
                                            {
                                                "to": "ada@example.com",
                                                "message_id": "<01JBT8XQ2M@yourdomain.com>"
                                            },
                                            {
                                                "to": "grace@example.com",
                                                "error": "Recipient is suppressed."
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "One shared template and a list of recipients, each with their own `variables`.\nUp to 500 recipients per call.\n\n**A partial failure is not an error.** Every recipient is processed independently, so\none suppressed or malformed address does not stop the rest \u2014 the call still returns\n`200` and the per-recipient outcome is in `results`. Check `failed` rather than the\nstatus code, or you will silently lose mail you believe you sent.\n\nThis is for transactional mail going to many people at once. For marketing sends to a\nlist or segment, use [campaigns](/developer/api/campaigns) instead: they add\nunsubscribe handling, review and reporting that this endpoint deliberately does not.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "messages",
                                    "from"
                                ],
                                "properties": {
                                    "messages": {
                                        "type": "array",
                                        "maxItems": 500,
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "to"
                                            ],
                                            "properties": {
                                                "to": {
                                                    "type": "string",
                                                    "format": "email",
                                                    "description": "This recipient's address."
                                                },
                                                "variables": {
                                                    "type": "object",
                                                    "additionalProperties": true,
                                                    "description": "Values for this recipient's `{{ tags }}`, like `{\"name\": \"Ada\"}`."
                                                }
                                            }
                                        },
                                        "description": "The recipients, 1 to 500, each with their own `variables`."
                                    },
                                    "from": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "The sender address for every message. It must be a verified sender in your organization.",
                                        "example": "hello@yourdomain.com"
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The subject for every message. It can use `{{ tags }}`. Needed unless `template_id` is given.",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "type": "string",
                                        "description": "The HTML for every message, with `{{ tags }}` filled from each recipient's `variables`.",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    },
                                    "text": {
                                        "type": "string",
                                        "description": "The plain-text version of the email.",
                                        "x-example": "Hi {{name}}, here is what is new this month."
                                    },
                                    "template_id": {
                                        "type": "string",
                                        "description": "Optional. One of your templates to use instead of `subject` and `html`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "tags": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 64
                                        },
                                        "description": "Your own labels, returned on the delivery events for these messages."
                                    }
                                }
                            },
                            "example": {
                                "from": "hello@yourdomain.com",
                                "subject": "Your weekly summary",
                                "template_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                "messages": [
                                    {
                                        "to": "ada@example.com",
                                        "variables": {
                                            "first_name": "Ada"
                                        }
                                    },
                                    {
                                        "to": "grace@example.com",
                                        "variables": {
                                            "first_name": "Grace"
                                        }
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/messages/scheduled": {
            "post": {
                "operationId": "postMessagesScheduled",
                "summary": "Schedule a message",
                "tags": [
                    "Sending"
                ],
                "x-required-scope": "messages:send",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "description": "Makes this request safe to retry. Use `<app>-<ULID>`, such as `crm-01JBT8XQ2M9WYC3K4F6R7S8T9V`; any other shape is a 422. Send the same key on every retry: a repeat gets the first answer with `Idempotency-Replayed: true`, a key reused for a different request is a 422, and one still running is a 409 with `Retry-After`. Keys last 24 hours, per organization.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z][a-z0-9]{0,19}-[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
                            "example": "crm-01JBT8XQ2M9WYC3K4F6R7S8T9V"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "201 with the `scheduled_message`. Use its `id` to list, inspect or cancel it.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "A message accepted now and submitted at `send_at`. It is not a `message`: a message has left, and this has not. Once it goes, `message_id` names the message it became.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "scheduled_message"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Address this with `GET` and `DELETE /messages/scheduled/{id}`. It identifies the SCHEDULE, not the message \u2014 see `message_id`."
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "scheduled",
                                                                "sending",
                                                                "sent",
                                                                "cancelled",
                                                                "failed"
                                                            ],
                                                            "description": "`scheduled` (waiting), `sending` (going out now; it can no longer be cancelled), `sent`, `cancelled` or `failed`."
                                                        },
                                                        "mode": {
                                                            "type": "string",
                                                            "enum": [
                                                                "live",
                                                                "test"
                                                            ],
                                                            "description": "`test` when a test API key scheduled this message: when it is due it is stored in your Sandbox, never delivered. Otherwise `live`."
                                                        },
                                                        "send_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When it will be sent, to the minute."
                                                        },
                                                        "from": {
                                                            "type": "string",
                                                            "description": "The sender, as scheduled."
                                                        },
                                                        "to": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The recipients, as scheduled. `cc` and `bcc` are held but not published back \u2014 a Bcc that reappears in a readable response is a Bcc that leaked."
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "`null` MEANS NONE WAS SET \u2014 a message may legitimately have no subject, and a template supplies its own at render time."
                                                        },
                                                        "message_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Message-ID it was sent with. Null until it is sent, and for a cancelled or failed message."
                                                        },
                                                        "sent_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was submitted. `null` MEANS IT HAS NOT BEEN."
                                                        },
                                                        "cancelled_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was cancelled. `null` MEANS IT WAS NOT."
                                                        },
                                                        "failure_reason": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Why it could not be sent. Set only when `status` is `failed`. Suppression and rate limits are checked when the message is sent, not when it was scheduled."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When it was accepted."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Accepts a message now and submits it at `send_at`. The body is exactly `POST /messages`,\nplus `send_at`.\n\n**It is a separate endpoint, and that is deliberate.** Other providers put the delivery time\non the send call, and the cost of that is a send endpoint whose response is a message on one\ncall and a schedule on the next \u2014 two object types from one operation. Here you get a\n`message` from `/messages` and a `scheduled_message` from `/messages/scheduled`, always.\n`POST /messages` **refuses** a `send_at` rather than ignoring it: a scheduling parameter\nthat is silently dropped delivers the message immediately, to everyone, at the wrong time,\nwith nothing said.\n\n**Everything that can be checked now is checked now** \u2014 the body, the recipients, the\nattachments, the limits, and that `from` is a verified Sender of yours. A scheduled send\nthat fails validation three days later is a message that silently never went, and you find\nout from the recipient.\n\n**Suppression and rate limits are checked when it leaves, not when you schedule it.** They\nare questions about the world at the moment of delivery: somebody who unsubscribes on\nTuesday must not receive a message you scheduled on Monday. When that happens the row ends\n`failed` with `failure_reason` set, so it says what happened rather than disappearing.\n\n`send_at` must be at least 60 seconds ahead \u2014 the sweep runs every minute and we will not\npromise a precision we do not have \u2014 and at most 30 days, because the whole message,\nattachments included, is stored here until it goes.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "to",
                                    "from",
                                    "send_at"
                                ],
                                "properties": {
                                    "send_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "When to send, in ISO 8601 with a time zone. At least 60 seconds and at most 30 days ahead. A time in the past is refused."
                                    }
                                },
                                "description": "Every field of `POST /messages`, plus `send_at`."
                            },
                            "example": {
                                "to": [
                                    "ada@example.com"
                                ],
                                "from": "hello@yourdomain.com",
                                "subject": "Your weekly summary",
                                "text": "Here is what happened this week.",
                                "send_at": "2026-09-21T09:00:00Z"
                            }
                        }
                    }
                }
            },
            "get": {
                "operationId": "getMessagesScheduled",
                "summary": "List scheduled messages",
                "tags": [
                    "Sending"
                ],
                "x-required-scope": "messages:send",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "One of `scheduled`, `sending`, `sent`, `cancelled`, `failed`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Page size.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "description": "A message accepted now and submitted at `send_at`. It is not a `message`: a message has left, and this has not. Once it goes, `message_id` names the message it became.",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "scheduled_message"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Address this with `GET` and `DELETE /messages/scheduled/{id}`. It identifies the SCHEDULE, not the message \u2014 see `message_id`."
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "scheduled",
                                                                            "sending",
                                                                            "sent",
                                                                            "cancelled",
                                                                            "failed"
                                                                        ],
                                                                        "description": "`scheduled` (waiting), `sending` (going out now; it can no longer be cancelled), `sent`, `cancelled` or `failed`."
                                                                    },
                                                                    "mode": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "live",
                                                                            "test"
                                                                        ],
                                                                        "description": "`test` when a test API key scheduled this message: when it is due it is stored in your Sandbox, never delivered. Otherwise `live`."
                                                                    },
                                                                    "send_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "description": "When it will be sent, to the minute."
                                                                    },
                                                                    "from": {
                                                                        "type": "string",
                                                                        "description": "The sender, as scheduled."
                                                                    },
                                                                    "to": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "The recipients, as scheduled. `cc` and `bcc` are held but not published back \u2014 a Bcc that reappears in a readable response is a Bcc that leaked."
                                                                    },
                                                                    "subject": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "`null` MEANS NONE WAS SET \u2014 a message may legitimately have no subject, and a template supplies its own at render time."
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The Message-ID it was sent with. Null until it is sent, and for a cancelled or failed message."
                                                                    },
                                                                    "sent_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When it was submitted. `null` MEANS IT HAS NOT BEEN."
                                                                    },
                                                                    "cancelled_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When it was cancelled. `null` MEANS IT WAS NOT."
                                                                    },
                                                                    "failure_reason": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why it could not be sent. Set only when `status` is `failed`. Suppression and rate limits are checked when the message is sent, not when it was scheduled."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "description": "When it was accepted."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Your scheduled messages, **soonest first** \u2014 the opposite order to every other list here,\nbecause this one is about what is about to happen and newest-first would bury the next send\nunder everything already gone.\n\nBodies are not echoed back. You already have the message you scheduled, and repeating up to\n10 MB of base64 attachments in every row would make the list unusable. What comes back is\nthe envelope: to, from, subject, and what is going to happen to it."
            }
        },
        "/api/v1/messages/scheduled/{scheduled}": {
            "get": {
                "operationId": "getMessagesScheduledScheduled",
                "summary": "Retrieve a message",
                "tags": [
                    "Sending"
                ],
                "x-required-scope": "messages:send",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "scheduled",
                        "in": "path",
                        "required": true,
                        "description": "The scheduled identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "A message accepted now and submitted at `send_at`. It is not a `message`: a message has left, and this has not. Once it goes, `message_id` names the message it became.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "scheduled_message"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Address this with `GET` and `DELETE /messages/scheduled/{id}`. It identifies the SCHEDULE, not the message \u2014 see `message_id`."
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "scheduled",
                                                                "sending",
                                                                "sent",
                                                                "cancelled",
                                                                "failed"
                                                            ],
                                                            "description": "`scheduled` (waiting), `sending` (going out now; it can no longer be cancelled), `sent`, `cancelled` or `failed`."
                                                        },
                                                        "mode": {
                                                            "type": "string",
                                                            "enum": [
                                                                "live",
                                                                "test"
                                                            ],
                                                            "description": "`test` when a test API key scheduled this message: when it is due it is stored in your Sandbox, never delivered. Otherwise `live`."
                                                        },
                                                        "send_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When it will be sent, to the minute."
                                                        },
                                                        "from": {
                                                            "type": "string",
                                                            "description": "The sender, as scheduled."
                                                        },
                                                        "to": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The recipients, as scheduled. `cc` and `bcc` are held but not published back \u2014 a Bcc that reappears in a readable response is a Bcc that leaked."
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "`null` MEANS NONE WAS SET \u2014 a message may legitimately have no subject, and a template supplies its own at render time."
                                                        },
                                                        "message_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Message-ID it was sent with. Null until it is sent, and for a cancelled or failed message."
                                                        },
                                                        "sent_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was submitted. `null` MEANS IT HAS NOT BEEN."
                                                        },
                                                        "cancelled_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was cancelled. `null` MEANS IT WAS NOT."
                                                        },
                                                        "failure_reason": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Why it could not be sent. Set only when `status` is `failed`. Suppression and rate limits are checked when the message is sent, not when it was scheduled."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When it was accepted."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "delete": {
                "operationId": "deleteMessagesScheduledScheduled",
                "summary": "Cancel a scheduled message",
                "tags": [
                    "Sending"
                ],
                "x-required-scope": "messages:send",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "scheduled",
                        "in": "path",
                        "required": true,
                        "description": "The scheduled identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 with the `scheduled_message`, now `cancelled`. 422 if it is too late, naming the state it is in. 404 if it is not yours.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "A message accepted now and submitted at `send_at`. It is not a `message`: a message has left, and this has not. Once it goes, `message_id` names the message it became.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "scheduled_message"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Address this with `GET` and `DELETE /messages/scheduled/{id}`. It identifies the SCHEDULE, not the message \u2014 see `message_id`."
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "scheduled",
                                                                "sending",
                                                                "sent",
                                                                "cancelled",
                                                                "failed"
                                                            ],
                                                            "description": "`scheduled` (waiting), `sending` (going out now; it can no longer be cancelled), `sent`, `cancelled` or `failed`."
                                                        },
                                                        "mode": {
                                                            "type": "string",
                                                            "enum": [
                                                                "live",
                                                                "test"
                                                            ],
                                                            "description": "`test` when a test API key scheduled this message: when it is due it is stored in your Sandbox, never delivered. Otherwise `live`."
                                                        },
                                                        "send_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When it will be sent, to the minute."
                                                        },
                                                        "from": {
                                                            "type": "string",
                                                            "description": "The sender, as scheduled."
                                                        },
                                                        "to": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The recipients, as scheduled. `cc` and `bcc` are held but not published back \u2014 a Bcc that reappears in a readable response is a Bcc that leaked."
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "`null` MEANS NONE WAS SET \u2014 a message may legitimately have no subject, and a template supplies its own at render time."
                                                        },
                                                        "message_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Message-ID it was sent with. Null until it is sent, and for a cancelled or failed message."
                                                        },
                                                        "sent_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was submitted. `null` MEANS IT HAS NOT BEEN."
                                                        },
                                                        "cancelled_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was cancelled. `null` MEANS IT WAS NOT."
                                                        },
                                                        "failure_reason": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Why it could not be sent. Set only when `status` is `failed`. Suppression and rate limits are checked when the message is sent, not when it was scheduled."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When it was accepted."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Stops a message that has not been sent.\n\n**Only while its status is `scheduled`.** Once the sweep has claimed it \u2014 status `sending` \u2014\nthe message may already be on the wire, and there is no such thing as unsending. The cancel\nis then refused with a message naming the state it is actually in and, for one already sent,\nwhen it went. A success you could not act on would be worse than a refusal.\n\nThe cancel and the sweep are the same conditional update on one row, so exactly one of them\ncan win. You are never told a message was cancelled when it was not."
            }
        },
        "/api/v1/domains/{domain}/messages/{messageId}": {
            "get": {
                "operationId": "getDomainsDomainMessagesMessageId",
                "summary": "Retrieve a stored message",
                "tags": [
                    "Sending"
                ],
                "x-required-scope": "events:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "messageId",
                        "in": "path",
                        "required": true,
                        "description": "The message id exactly as it arrived, angle brackets included.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "archived_message",
                                                                "archived_message_preview"
                                                            ],
                                                            "description": "Which of the two shapes you got. `archived_message` is the default and carries `raw`; `archived_message_preview` is `?format=html` and carries the parsed fields instead. Branch on this, never on the presence of a key."
                                                        },
                                                        "message_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Message-ID, angle brackets included, as the send returned it."
                                                        },
                                                        "domain": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The domain this copy is archived under."
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the message was archived. Null if the stored copy has no date."
                                                        },
                                                        "legal_hold": {
                                                            "type": "boolean",
                                                            "description": "Default shape only. True means retention cannot expire this copy."
                                                        },
                                                        "raw": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The raw message (`message/rfc822`) exactly as stored: headers, body and attachments. It is not made safe, so do not show it in a browser; use `?format=html` for that. Not present with `?format=html`."
                                                        },
                                                        "headers": {
                                                            "type": "object",
                                                            "additionalProperties": {
                                                                "type": "string"
                                                            },
                                                            "description": "`?format=html` only. The parsed headers, name to value."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "With `?format=html` only: the HTML body, made safe to display, with scripts and remote content removed. Null when the message has no HTML part; show `text` instead."
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "With `?format=html` only: the plain-text body. Null when the message has no plain-text part. `html` and `text` can both be null."
                                                        },
                                                        "attachments": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object"
                                                            },
                                                            "description": "With `?format=html` only: each attachment's name, type and size, not the file itself."
                                                        },
                                                        "blocked_remote_count": {
                                                            "type": "integer",
                                                            "description": "With `?format=html` only: how many remote images or other content were blocked, so you can tell the reader."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "The archived copy of a message, which is what a webhook's `storage.url` points at.\n\n`messageId` is the id **exactly as it arrived**, angle brackets included. Stripping\nthem returns `404`: the archive stores the id as it was received, and a bridge that\nhelpfully removed `<` and `>` is why every inbound message 404'd here until\n2026-09-14."
            }
        },
        "/api/v1/email-templates": {
            "get": {
                "operationId": "getEmailTemplates",
                "summary": "List templates",
                "tags": [
                    "Templates"
                ],
                "x-required-scope": "templates:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "email_template"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "Unique within your organization."
                                                                    },
                                                                    "subject": {
                                                                        "type": "string",
                                                                        "description": "May contain `{{ variable }}` placeholders, like the bodies. Required when the template is created and never null afterwards; an update that omits it keeps the stored one rather than clearing it."
                                                                    },
                                                                    "html": {
                                                                        "type": "string",
                                                                        "description": "The HTML body. An empty body is `\"\"`."
                                                                    },
                                                                    "text": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The plain-text body. When you create or update a template, send it as `plain_text`."
                                                                    },
                                                                    "variables": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "The `{{ }}` placeholder names used in the subject and bodies. `[]` when there are none."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the template was created."
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the template was last saved."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Every stored template in your organization, newest first."
            },
            "post": {
                "operationId": "postEmailTemplates",
                "summary": "Create a email template",
                "tags": [
                    "Templates"
                ],
                "x-required-scope": "templates:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "email_template"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Unique within your organization."
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "description": "May contain `{{ variable }}` placeholders, like the bodies. Required when the template is created and never null afterwards; an update that omits it keeps the stored one rather than clearing it."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "description": "The HTML body. An empty body is `\"\"`."
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The plain-text body. When you create or update a template, send it as `plain_text`."
                                                        },
                                                        "variables": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The `{{ }}` placeholder names used in the subject and bodies. `[]` when there are none."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the template was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the template was last saved."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "skeleton_html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional, advanced. Your own HTML with `data-my-edit` on the parts people may change in the dashboard. We build `html` from it and `content`."
                                    },
                                    "content": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "For a template made from a design (`source_template_key`) or from `skeleton_html`: the text and images for each editable part, keyed by the part's name. Not used with plain `html`.",
                                        "x-example": {
                                            "headline": "Our October update"
                                        }
                                    },
                                    "source_template_key": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Optional. Make the template from one of our ready-made designs, by the design's key. We build `html` from the design, your brand kit and `content`."
                                    },
                                    "layout": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 50,
                                        "description": "For a template made from a design: which version of the design, for example `branded` or `plain`. A name the design does not have falls back to its default.",
                                        "x-example": "branded"
                                    },
                                    "show_company_name": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "For a template made from a design: show your company name at the top. Leave it out, or send null, to follow your brand kit.",
                                        "x-example": true
                                    },
                                    "plain_text": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. The plain-text version sent with the HTML.",
                                        "x-example": "Hi {{name}},\n\nHere is what is new this month."
                                    },
                                    "variables_schema": {
                                        "nullable": true,
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Optional. The `{{ tag }}` names this template uses, such as `[\"name\", \"order_number\"]`. Leave it out and we find them in the template."
                                    },
                                    "name": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Order receipt`. It must be different from your other templates' names.",
                                        "example": "Order receipt",
                                        "x-example": "Spring newsletter"
                                    },
                                    "subject": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The subject line. It can use `{{ tags }}` like `{{order_number}}`.",
                                        "example": "Your receipt for order {{order_number}}",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "The template's HTML, with `{{ tags }}` where your values go. Needed when you create a template, unless it is made from a design (`source_template_key`) or from `skeleton_html`.",
                                        "example": "<p>Hi {{name}},</p><p>Thanks for your order {{order_number}}.</p>",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    }
                                }
                            },
                            "example": {
                                "name": "Order receipt",
                                "subject": "Your receipt for order {{order_number}}",
                                "html": "<p>Hi {{name}},</p><p>Thanks for your order {{order_number}}.</p>"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-templates/preview": {
            "post": {
                "operationId": "postEmailTemplatesPreview",
                "summary": "Preview a rendered template",
                "tags": [
                    "Templates"
                ],
                "x-required-scope": "templates:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "template_preview"
                                                            ]
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The subject with `{{ }}` variables filled in, as a real send would show it. Null when you sent no `subject`. `\"\"` usually means a placeholder you gave no value for."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The HTML with `{{ }}` variables filled in; values are HTML-escaped here. Null when you sent no `html`. This endpoint previews only what you post: it does not load a saved template."
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rendered plain-text body. The REQUEST field for it is `plain_text`, not `text`: this endpoint validates `plain_text` and drops a `text` key, so posting `text` renders nothing and returns null here."
                                                        },
                                                        "variables": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The `{{ }}` placeholder names found in what you sent, whether or not you gave them values."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Renders a template with the variables you supply and returns the result without\nsending anything. Worth calling in your own test suite: it is the cheapest way to\ncatch a variable you renamed on one side and not the other.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "subject": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The subject line to preview.",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "The HTML to preview, with `{{ tags }}`.",
                                        "example": "<p>Hi {{name}}</p>",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    },
                                    "skeleton_html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional, advanced. Your own HTML with `data-my-edit` on the parts people may change in the dashboard. We build `html` from it and `content`."
                                    },
                                    "source_template_key": {
                                        "type": "string",
                                        "description": "Optional. Make the template from one of our ready-made designs, by the design's key. We build `html` from the design, your brand kit and `content`."
                                    },
                                    "content": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "For a template made from a design (`source_template_key`) or from `skeleton_html`: the text and images for each editable part, keyed by the part's name. Not used with plain `html`.",
                                        "x-example": {
                                            "headline": "Our October update"
                                        }
                                    },
                                    "layout": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 50,
                                        "description": "For a template made from a design: which version of the design, for example `branded` or `plain`. A name the design does not have falls back to its default.",
                                        "x-example": "branded"
                                    },
                                    "show_company_name": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "For a template made from a design: show your company name at the top. Leave it out, or send null, to follow your brand kit.",
                                        "x-example": true
                                    },
                                    "plain_text": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Plain text to preview. With `plain: true`, it is laid out exactly as a plain email is sent.",
                                        "x-example": "Hi {{name}},\n\nHere is what is new this month."
                                    },
                                    "plain": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Send `true` to preview `plain_text` as a plain email, exactly as it would be sent."
                                    },
                                    "variables": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "Sample values for the `{{ tags }}`, like `{\"name\": \"Ada\"}`. `email` and `organization_name` are filled for you.",
                                        "example": {
                                            "name": "Ada"
                                        }
                                    },
                                    "brand": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "Optional. Brand kit values to try before saving them (logo, colours, company name)."
                                    }
                                }
                            },
                            "example": {
                                "html": "<p>Hi {{name}}</p>",
                                "variables": {
                                    "name": "Ada"
                                }
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-templates/{email_template}": {
            "get": {
                "operationId": "getEmailTemplatesEmailTemplate",
                "summary": "Retrieve a email template",
                "tags": [
                    "Templates"
                ],
                "x-required-scope": "templates:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "email_template",
                        "in": "path",
                        "required": true,
                        "description": "The email template identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "email_template"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Unique within your organization."
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "description": "May contain `{{ variable }}` placeholders, like the bodies. Required when the template is created and never null afterwards; an update that omits it keeps the stored one rather than clearing it."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "description": "The HTML body. An empty body is `\"\"`."
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The plain-text body. When you create or update a template, send it as `plain_text`."
                                                        },
                                                        "variables": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The `{{ }}` placeholder names used in the subject and bodies. `[]` when there are none."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the template was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the template was last saved."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putEmailTemplatesEmailTemplate",
                "summary": "Update a email template",
                "tags": [
                    "Templates"
                ],
                "x-required-scope": "templates:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "email_template",
                        "in": "path",
                        "required": true,
                        "description": "The email template identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "email_template"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Unique within your organization."
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "description": "May contain `{{ variable }}` placeholders, like the bodies. Required when the template is created and never null afterwards; an update that omits it keeps the stored one rather than clearing it."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "description": "The HTML body. An empty body is `\"\"`."
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The plain-text body. When you create or update a template, send it as `plain_text`."
                                                        },
                                                        "variables": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The `{{ }}` placeholder names used in the subject and bodies. `[]` when there are none."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the template was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the template was last saved."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "skeleton_html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional, advanced. Your own HTML with `data-my-edit` on the parts people may change in the dashboard. We build `html` from it and `content`."
                                    },
                                    "content": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "For a template made from a design (`source_template_key`) or from `skeleton_html`: the text and images for each editable part, keyed by the part's name. Not used with plain `html`.",
                                        "x-example": {
                                            "headline": "Our October update"
                                        }
                                    },
                                    "source_template_key": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Optional. Make the template from one of our ready-made designs, by the design's key. We build `html` from the design, your brand kit and `content`."
                                    },
                                    "layout": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 50,
                                        "description": "For a template made from a design: which version of the design, for example `branded` or `plain`. A name the design does not have falls back to its default.",
                                        "x-example": "branded"
                                    },
                                    "show_company_name": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "For a template made from a design: show your company name at the top. Leave it out, or send null, to follow your brand kit.",
                                        "x-example": true
                                    },
                                    "plain_text": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. The plain-text version sent with the HTML.",
                                        "x-example": "Hi {{name}},\n\nHere is what is new this month."
                                    },
                                    "variables_schema": {
                                        "nullable": true,
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Optional. The `{{ tag }}` names this template uses, such as `[\"name\", \"order_number\"]`. Leave it out and we find them in the template."
                                    },
                                    "name": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Order receipt`. It must be different from your other templates' names.",
                                        "example": "Order receipt",
                                        "x-example": "Spring newsletter"
                                    },
                                    "subject": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The subject line. It can use `{{ tags }}` like `{{order_number}}`.",
                                        "example": "Your receipt for order {{order_number}}",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "The template's HTML, with `{{ tags }}` where your values go. Needed when you create a template, unless it is made from a design (`source_template_key`) or from `skeleton_html`.",
                                        "example": "<p>Hi {{name}},</p><p>Thanks for your order {{order_number}}.</p>",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    }
                                }
                            },
                            "example": {
                                "name": "Order receipt",
                                "subject": "Your receipt for order {{order_number}}",
                                "html": "<p>Hi {{name}},</p><p>Thanks for your order {{order_number}}.</p>"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "patch": {
                "operationId": "patchEmailTemplatesEmailTemplate",
                "summary": "Update a email template",
                "tags": [
                    "Templates"
                ],
                "x-required-scope": "templates:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "email_template",
                        "in": "path",
                        "required": true,
                        "description": "The email template identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "email_template"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Unique within your organization."
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "description": "May contain `{{ variable }}` placeholders, like the bodies. Required when the template is created and never null afterwards; an update that omits it keeps the stored one rather than clearing it."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "description": "The HTML body. An empty body is `\"\"`."
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The plain-text body. When you create or update a template, send it as `plain_text`."
                                                        },
                                                        "variables": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The `{{ }}` placeholder names used in the subject and bodies. `[]` when there are none."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the template was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the template was last saved."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "skeleton_html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional, advanced. Your own HTML with `data-my-edit` on the parts people may change in the dashboard. We build `html` from it and `content`."
                                    },
                                    "content": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "For a template made from a design (`source_template_key`) or from `skeleton_html`: the text and images for each editable part, keyed by the part's name. Not used with plain `html`.",
                                        "x-example": {
                                            "headline": "Our October update"
                                        }
                                    },
                                    "source_template_key": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Optional. Make the template from one of our ready-made designs, by the design's key. We build `html` from the design, your brand kit and `content`."
                                    },
                                    "layout": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 50,
                                        "description": "For a template made from a design: which version of the design, for example `branded` or `plain`. A name the design does not have falls back to its default.",
                                        "x-example": "branded"
                                    },
                                    "show_company_name": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "For a template made from a design: show your company name at the top. Leave it out, or send null, to follow your brand kit.",
                                        "x-example": true
                                    },
                                    "plain_text": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. The plain-text version sent with the HTML.",
                                        "x-example": "Hi {{name}},\n\nHere is what is new this month."
                                    },
                                    "variables_schema": {
                                        "nullable": true,
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Optional. The `{{ tag }}` names this template uses, such as `[\"name\", \"order_number\"]`. Leave it out and we find them in the template."
                                    },
                                    "name": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Order receipt`. It must be different from your other templates' names.",
                                        "example": "Order receipt",
                                        "x-example": "Spring newsletter"
                                    },
                                    "subject": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The subject line. It can use `{{ tags }}` like `{{order_number}}`.",
                                        "example": "Your receipt for order {{order_number}}",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "The template's HTML, with `{{ tags }}` where your values go. Needed when you create a template, unless it is made from a design (`source_template_key`) or from `skeleton_html`.",
                                        "example": "<p>Hi {{name}},</p><p>Thanks for your order {{order_number}}.</p>",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    }
                                }
                            },
                            "example": {
                                "name": "Order receipt",
                                "subject": "Your receipt for order {{order_number}}",
                                "html": "<p>Hi {{name}},</p><p>Thanks for your order {{order_number}}.</p>"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteEmailTemplatesEmailTemplate",
                "summary": "Delete a email template",
                "tags": [
                    "Templates"
                ],
                "x-required-scope": "templates:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "email_template",
                        "in": "path",
                        "required": true,
                        "description": "The email template identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The template is gone; messages already sent from it are unaffected, and a second delete of the same id is a 404."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains": {
            "get": {
                "operationId": "getDomains",
                "summary": "List domains",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "domain"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Unique identifier for the domain."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The domain itself, e.g. `example.com`."
                                                                    },
                                                                    "description": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Your own note on the domain. Null when none was set."
                                                                    },
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "active",
                                                                            "provisioning",
                                                                            "failed",
                                                                            "disabled"
                                                                        ],
                                                                        "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                                    },
                                                                    "provisioning": {
                                                                        "type": "object",
                                                                        "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                                        "properties": {
                                                                            "state": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "pending",
                                                                                    "provisioning",
                                                                                    "active",
                                                                                    "failed",
                                                                                    "suspended",
                                                                                    "deleting",
                                                                                    "deleted"
                                                                                ],
                                                                                "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                            },
                                                                            "error": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                            },
                                                                            "retryable": {
                                                                                "type": "boolean",
                                                                                "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                            }
                                                                        }
                                                                    },
                                                                    "sending": {
                                                                        "type": "object",
                                                                        "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                                        "properties": {
                                                                            "enabled": {
                                                                                "type": "boolean"
                                                                            },
                                                                            "requires": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    },
                                                                    "receiving": {
                                                                        "type": "object",
                                                                        "description": "Receiving needs MX.",
                                                                        "properties": {
                                                                            "enabled": {
                                                                                "type": "boolean"
                                                                            },
                                                                            "requires": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    },
                                                                    "limits": {
                                                                        "type": "object",
                                                                        "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                                        "properties": {
                                                                            "storage_bytes": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                            },
                                                                            "max_mailboxes": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many mailboxes this domain may have. The default is 50."
                                                                            },
                                                                            "mailboxes_used": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many mailboxes the domain has now."
                                                                            }
                                                                        }
                                                                    },
                                                                    "defaults": {
                                                                        "type": "object",
                                                                        "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                                        "properties": {
                                                                            "mailbox_storage_bytes": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                            }
                                                                        }
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postDomains",
                "summary": "Add a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the domain."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note on the domain. Null when none was set."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                }
                                                            }
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Receiving needs MX.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                            "properties": {
                                                                "storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                },
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes this domain may have. The default is 50."
                                                                },
                                                                "mailboxes_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes the domain has now."
                                                                }
                                                            }
                                                        },
                                                        "defaults": {
                                                            "type": "object",
                                                            "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                            "properties": {
                                                                "mailbox_storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Registers a domain and returns the DNS records to publish. Nothing can be sent from it\nuntil those records are live and verification has passed.\n\nAdding a domain does **not** create any mailboxes. A domain with no mailboxes accepts\ninbound mail and then has nowhere to put it, so create at least one before pointing MX\nat us.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain": {
                                        "type": "string",
                                        "description": "The domain to add, like `yourdomain.com`: no `https://`, no `www.`.",
                                        "example": "yourdomain.com",
                                        "x-example": "yourdomain.com"
                                    },
                                    "description": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    },
                                    "storage_quota": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 1000000,
                                        "description": "Optional. Total storage for all mailboxes on this domain, in megabytes.",
                                        "x-example": 10240
                                    },
                                    "max_email_accounts": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 10000,
                                        "description": "Optional. The most mailboxes this domain may have.",
                                        "x-example": 25
                                    },
                                    "default_email_account_storage_quota": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 100000,
                                        "description": "Optional. Storage a new mailbox on this domain gets, in megabytes, unless you give it its own.",
                                        "x-example": 5120
                                    }
                                },
                                "required": [
                                    "domain"
                                ]
                            },
                            "example": {
                                "domain": "yourdomain.com"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/domains/stats": {
            "get": {
                "operationId": "getDomainsStats",
                "summary": "Stats (domain)",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain_stats"
                                                            ]
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Every domain this organization holds that is not deleted or hidden."
                                                        },
                                                        "active": {
                                                            "type": "integer",
                                                            "description": "Domains marked active."
                                                        },
                                                        "inactive": {
                                                            "type": "integer",
                                                            "description": "Domains not yet active, usually waiting for DNS."
                                                        },
                                                        "dns_failed": {
                                                            "type": "integer",
                                                            "description": "Domains whose last DNS check failed. This OVERLAPS `inactive`: the three counts do not sum to `total`."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/bulk-delete": {
            "post": {
                "operationId": "postDomainsBulkDelete",
                "summary": "Delete several domains",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "bulk_result"
                                                            ]
                                                        },
                                                        "action": {
                                                            "type": "string",
                                                            "enum": [
                                                                "verify",
                                                                "delete",
                                                                "activate",
                                                                "suspend"
                                                            ],
                                                            "description": "What was attempted against every id."
                                                        },
                                                        "requested": {
                                                            "type": "integer",
                                                            "description": "How many ids were submitted."
                                                        },
                                                        "succeeded": {
                                                            "type": "integer"
                                                        },
                                                        "failed": {
                                                            "type": "integer"
                                                        },
                                                        "results": {
                                                            "type": "array",
                                                            "description": "Every submitted id with its own outcome, in submission order. A bulk call is partial by nature: `succeeded` and `failed` both being non-zero is an ordinary result, not an error.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The domain id as submitted. Null on a failure the operation could not attribute to one."
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "succeeded",
                                                                            "failed"
                                                                        ]
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why this one failed. Null when it succeeded."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "domain_ids"
                                ],
                                "properties": {
                                    "domain_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "IDs of your domains to act on. Read them from `GET /domains`.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "force_delete": {
                                        "type": "boolean",
                                        "default": false,
                                        "description": "Ordinarily a domain is soft-deleted and can be restored. True removes it permanently, along with anything that cascades from it."
                                    }
                                }
                            },
                            "example": {
                                "domain_ids": [
                                    "01m2q1qc6skqy6k2sq88abm4pw"
                                ],
                                "force_delete": false
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/domains/bulk-update": {
            "post": {
                "operationId": "postDomainsBulkUpdate",
                "summary": "Bulk Update (domain)",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "bulk_result"
                                                            ]
                                                        },
                                                        "action": {
                                                            "type": "string",
                                                            "enum": [
                                                                "verify",
                                                                "delete",
                                                                "activate",
                                                                "suspend"
                                                            ],
                                                            "description": "What was attempted against every id."
                                                        },
                                                        "requested": {
                                                            "type": "integer",
                                                            "description": "How many ids were submitted."
                                                        },
                                                        "succeeded": {
                                                            "type": "integer"
                                                        },
                                                        "failed": {
                                                            "type": "integer"
                                                        },
                                                        "results": {
                                                            "type": "array",
                                                            "description": "Every submitted id with its own outcome, in submission order. A bulk call is partial by nature: `succeeded` and `failed` both being non-zero is an ordinary result, not an error.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The domain id as submitted. Null on a failure the operation could not attribute to one."
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "succeeded",
                                                                            "failed"
                                                                        ]
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why this one failed. Null when it succeeded."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain_ids": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "IDs of your domains to act on. Read them from `GET /domains`.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "verify",
                                            "activate",
                                            "suspend",
                                            "delete"
                                        ],
                                        "description": "What to do to every domain in `domain_ids`."
                                    },
                                    "settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "auto_verify": {
                                                "nullable": true,
                                                "type": "boolean",
                                                "description": "Check the DNS records again automatically."
                                            },
                                            "security_settings": {
                                                "nullable": true,
                                                "type": "object",
                                                "properties": {
                                                    "dmarc_policy": {
                                                        "nullable": true,
                                                        "type": "string",
                                                        "enum": [
                                                            "none",
                                                            "quarantine",
                                                            "reject"
                                                        ],
                                                        "description": "What receiving servers should do with mail that fails DMARC: `none`, `quarantine` or `reject`."
                                                    },
                                                    "dkim_enabled": {
                                                        "nullable": true,
                                                        "type": "boolean",
                                                        "description": "Sign this domain's mail with DKIM."
                                                    }
                                                },
                                                "description": "DMARC and DKIM preferences."
                                            }
                                        },
                                        "description": "Optional. Settings to apply with the action."
                                    }
                                },
                                "required": [
                                    "domain_ids",
                                    "action"
                                ]
                            },
                            "example": {
                                "domain_ids": [
                                    "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                ],
                                "action": "verify"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/domains/bulk-verify": {
            "post": {
                "operationId": "postDomainsBulkVerify",
                "summary": "Verify several domains",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "bulk_result"
                                                            ]
                                                        },
                                                        "action": {
                                                            "type": "string",
                                                            "enum": [
                                                                "verify",
                                                                "delete",
                                                                "activate",
                                                                "suspend"
                                                            ],
                                                            "description": "What was attempted against every id."
                                                        },
                                                        "requested": {
                                                            "type": "integer",
                                                            "description": "How many ids were submitted."
                                                        },
                                                        "succeeded": {
                                                            "type": "integer"
                                                        },
                                                        "failed": {
                                                            "type": "integer"
                                                        },
                                                        "results": {
                                                            "type": "array",
                                                            "description": "Every submitted id with its own outcome, in submission order. A bulk call is partial by nature: `succeeded` and `failed` both being non-zero is an ordinary result, not an error.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The domain id as submitted. Null on a failure the operation could not attribute to one."
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "succeeded",
                                                                            "failed"
                                                                        ]
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why this one failed. Null when it succeeded."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "domain_ids"
                                ],
                                "properties": {
                                    "domain_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Domains to re-check. Ids outside your organization are ignored.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "domain_ids": [
                                    "01m2q1qc6skqy6k2sq88abm4pw"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/domains/{domain}": {
            "get": {
                "operationId": "getDomainsDomain",
                "summary": "Retrieve a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the domain."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note on the domain. Null when none was set."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                }
                                                            }
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Receiving needs MX.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                            "properties": {
                                                                "storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                },
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes this domain may have. The default is 50."
                                                                },
                                                                "mailboxes_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes the domain has now."
                                                                }
                                                            }
                                                        },
                                                        "defaults": {
                                                            "type": "object",
                                                            "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                            "properties": {
                                                                "mailbox_storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putDomainsDomain",
                "summary": "Update a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the domain."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note on the domain. Null when none was set."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                }
                                                            }
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Receiving needs MX.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                            "properties": {
                                                                "storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                },
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes this domain may have. The default is 50."
                                                                },
                                                                "mailboxes_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes the domain has now."
                                                                }
                                                            }
                                                        },
                                                        "defaults": {
                                                            "type": "object",
                                                            "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                            "properties": {
                                                                "mailbox_storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Rename the domain, like `yourdomain.com`.",
                                        "x-example": "yourdomain.com"
                                    },
                                    "description": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    },
                                    "status": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "Active",
                                            "Inactive"
                                        ],
                                        "description": "Turn the domain off (`Inactive`) or back on (`Active`)."
                                    },
                                    "storage_quota": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 1000000,
                                        "description": "Optional. Total storage for all mailboxes on this domain, in megabytes.",
                                        "x-example": 10240
                                    },
                                    "max_email_accounts": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 10000,
                                        "description": "Optional. The most mailboxes this domain may have.",
                                        "x-example": 25
                                    },
                                    "default_email_account_storage_quota": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 100000,
                                        "description": "Optional. Storage a new mailbox on this domain gets, in megabytes, unless you give it its own.",
                                        "x-example": 5120
                                    },
                                    "is_active": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Whether it is switched on. Defaults to true.",
                                        "x-example": true
                                    },
                                    "settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "dmarc_policy": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "none",
                                                    "quarantine",
                                                    "reject"
                                                ],
                                                "description": "What receiving servers should do with mail that fails DMARC: `none`, `quarantine` or `reject`."
                                            },
                                            "spf_record": {
                                                "nullable": true,
                                                "type": "string",
                                                "description": "The SPF record you use for this domain."
                                            },
                                            "dkim_enabled": {
                                                "nullable": true,
                                                "type": "boolean",
                                                "description": "Sign this domain's mail with DKIM."
                                            },
                                            "mx_priority": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 65535,
                                                "description": "The MX record's priority, lowest first."
                                            }
                                        },
                                        "description": "Optional. DNS preferences saved with the domain."
                                    }
                                }
                            },
                            "example": {
                                "domain": "yourdomain.com",
                                "description": "Everyone who signed up at GITEX"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            },
            "patch": {
                "operationId": "patchDomainsDomain",
                "summary": "Update a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the domain."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note on the domain. Null when none was set."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                }
                                                            }
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Receiving needs MX.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                            "properties": {
                                                                "storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                },
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes this domain may have. The default is 50."
                                                                },
                                                                "mailboxes_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes the domain has now."
                                                                }
                                                            }
                                                        },
                                                        "defaults": {
                                                            "type": "object",
                                                            "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                            "properties": {
                                                                "mailbox_storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Rename the domain, like `yourdomain.com`.",
                                        "x-example": "yourdomain.com"
                                    },
                                    "description": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    },
                                    "status": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "Active",
                                            "Inactive"
                                        ],
                                        "description": "Turn the domain off (`Inactive`) or back on (`Active`)."
                                    },
                                    "storage_quota": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 1000000,
                                        "description": "Optional. Total storage for all mailboxes on this domain, in megabytes.",
                                        "x-example": 10240
                                    },
                                    "max_email_accounts": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 10000,
                                        "description": "Optional. The most mailboxes this domain may have.",
                                        "x-example": 25
                                    },
                                    "default_email_account_storage_quota": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 100000,
                                        "description": "Optional. Storage a new mailbox on this domain gets, in megabytes, unless you give it its own.",
                                        "x-example": 5120
                                    },
                                    "is_active": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Whether it is switched on. Defaults to true.",
                                        "x-example": true
                                    },
                                    "settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "dmarc_policy": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "none",
                                                    "quarantine",
                                                    "reject"
                                                ],
                                                "description": "What receiving servers should do with mail that fails DMARC: `none`, `quarantine` or `reject`."
                                            },
                                            "spf_record": {
                                                "nullable": true,
                                                "type": "string",
                                                "description": "The SPF record you use for this domain."
                                            },
                                            "dkim_enabled": {
                                                "nullable": true,
                                                "type": "boolean",
                                                "description": "Sign this domain's mail with DKIM."
                                            },
                                            "mx_priority": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 65535,
                                                "description": "The MX record's priority, lowest first."
                                            }
                                        },
                                        "description": "Optional. DNS preferences saved with the domain."
                                    }
                                }
                            },
                            "example": {
                                "domain": "yourdomain.com",
                                "description": "Everyone who signed up at GITEX"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteDomainsDomain",
                "summary": "Delete a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The domain and its mailboxes are removed."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/overview": {
            "get": {
                "operationId": "getDomainsDomainOverview",
                "summary": "Overview a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain_overview"
                                                            ]
                                                        },
                                                        "domain_id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The same lifecycle answer `GET /domains/{domain}` publishes, derived from the same fields."
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Identical to `sending` on the domain itself.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "spf",
                                                                            "dkim"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Identical to `receiving` on the domain itself.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "mx"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "mailboxes": {
                                                            "type": "object",
                                                            "description": "Mailbox counts for this domain. `active` and `suspended` may not add up to `total`: mailboxes in other states count only in `total`.",
                                                            "properties": {
                                                                "total": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Mailboxes on this domain. A live `COUNT`, never null; 0 means the domain genuinely has none."
                                                                },
                                                                "active": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Of those, how many are active. A live `COUNT`, never null; 0 is a measured zero."
                                                                },
                                                                "suspended": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Of those, how many are suspended. A live `COUNT`, never null; 0 is a measured zero, not an unread figure."
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "properties": {
                                                                "used_percent": {
                                                                    "type": "number",
                                                                    "nullable": true,
                                                                    "description": "Storage used by this domain's mailboxes, as a percentage of the domain's quota. Null when no quota is set."
                                                                }
                                                            }
                                                        },
                                                        "health_score": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "A score from 0 to 100; 100 means nothing is wrong. `GET /domains/{domain}/health` lists the problems behind it."
                                                        },
                                                        "checked_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When DNS was last resolved for this domain. Null when it never has been."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/dns-records": {
            "get": {
                "operationId": "getDomainsDomainDnsRecords",
                "summary": "Get the DNS records to publish",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "dns_records"
                                                            ]
                                                        },
                                                        "domain": {
                                                            "type": "string",
                                                            "description": "The domain these records belong to."
                                                        },
                                                        "records": {
                                                            "type": "array",
                                                            "description": "Every record to publish, required and optional together. Read `required_for` to tell them apart.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "purpose": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "spf",
                                                                            "dkim",
                                                                            "bounce",
                                                                            "mx",
                                                                            "dmarc",
                                                                            "autodiscover",
                                                                            "autoconfig",
                                                                            "_autodiscover"
                                                                        ],
                                                                        "description": "What the record is for. Matches the names in `checks` on the verification endpoint."
                                                                    },
                                                                    "type": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "txt",
                                                                            "mx",
                                                                            "cname",
                                                                            "srv",
                                                                            "a"
                                                                        ],
                                                                        "description": "The DNS record type, lowercased. DNS is case-insensitive about these, so it can be pasted into any console as-is."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The fully qualified name to create."
                                                                    },
                                                                    "value": {
                                                                        "type": "string",
                                                                        "description": "The value, verbatim. Do not reformat it."
                                                                    },
                                                                    "priority": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "The priority, for MX and SRV records only. Null for other types. (0 is a real priority, the highest.)"
                                                                    },
                                                                    "required_for": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "sending",
                                                                            "receiving"
                                                                        ],
                                                                        "description": "What this record is needed for. Null when it is optional."
                                                                    },
                                                                    "description": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "One line on what this record does, fine to show your users. Whether it is published yet is on `GET /domains/{domain}/verification-status`."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "fetched_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When these values were last read from the mail server. Null if never."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "The records this domain needs, with their current observed state.\n\nSending needs **SPF and DKIM**; MX is only needed to *receive*. Mailyte tracks those\nseparately (`dns_verified` and `mx_verified`) precisely so a customer who sends through\nus but keeps their mailboxes elsewhere is not blocked on an MX record they must not\npublish."
            }
        },
        "/api/v1/domains/{domain}/dkim": {
            "get": {
                "operationId": "getDomainsDomainDkim",
                "summary": "Dkim a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "dkim_key"
                                                            ]
                                                        },
                                                        "domain_id": {
                                                            "type": "string"
                                                        },
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "Whether a DKIM key has been made. Whether the record is published is `checks.dkim.verified` on the verification endpoint."
                                                        },
                                                        "selector": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The DKIM selector, always `default`. The record name is `default._domainkey.<your domain>`."
                                                        },
                                                        "record": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The record to publish, or null when no key has been generated yet.",
                                                            "properties": {
                                                                "type": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "txt"
                                                                    ]
                                                                },
                                                                "name": {
                                                                    "type": "string"
                                                                },
                                                                "value": {
                                                                    "type": "string",
                                                                    "description": "The public key record. The private half never leaves the mail server."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/dns-provider": {
            "get": {
                "operationId": "getDomainsDomainDnsProvider",
                "summary": "Dns Provider a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "dns_provider"
                                                            ]
                                                        },
                                                        "nameservers": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The domain's NS records. Empty when the domain does not resolve."
                                                        },
                                                        "provider": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Null when the nameservers match no provider we recognise. That is an ordinary answer, not an error.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "description": "A stable slug, e.g. `cloudflare`."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "description": "The provider's own name, for display."
                                                                },
                                                                "dns_panel_url": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "A link straight to this domain's DNS settings at the provider. Null when we know the provider but cannot build a link; send the user to `provider.name` instead."
                                                                }
                                                            }
                                                        },
                                                        "domain_connect": {
                                                            "type": "object",
                                                            "description": "Whether the provider advertises the Domain Connect standard, which can apply the records without the customer typing them.",
                                                            "properties": {
                                                                "supported": {
                                                                    "type": "boolean",
                                                                    "description": "Whether a `_domainconnect` discovery record was found. False also covers the case where the lookup itself failed, so it means \"not detected\" rather than \"confirmed absent\"."
                                                                },
                                                                "settings_url": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Where to send the user to add the records automatically. Set only when `supported` is true."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/verification-status": {
            "get": {
                "operationId": "getDomainsDomainVerificationStatus",
                "summary": "Verification Status a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain_verification"
                                                            ]
                                                        },
                                                        "domain_id": {
                                                            "type": "string"
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean",
                                                                    "description": "Whether this domain may send. The same value as `sending.enabled` on the domain itself."
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "spf",
                                                                            "dkim"
                                                                        ]
                                                                    },
                                                                    "description": "The records in `checks` that must pass for this verdict. The same list `GET /domains/{domain}` publishes."
                                                                },
                                                                "message": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why this verdict is false, or null when it is true. One record at a time: the first failure, not every failure."
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean",
                                                                    "description": "Whether mail addressed to this domain is delivered here. A send-only domain is expected to be false, and that is not a fault."
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "mx"
                                                                        ]
                                                                    },
                                                                    "description": "The records in `checks` that must pass for this verdict. The same list `GET /domains/{domain}` publishes."
                                                                },
                                                                "message": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why this verdict is false, or null when it is true. One record at a time: the first failure, not every failure."
                                                                }
                                                            }
                                                        },
                                                        "checks": {
                                                            "type": "object",
                                                            "description": "One entry per record, always all four, whether or not the mail server had an answer for it.",
                                                            "properties": {
                                                                "spf": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "required_for": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "sending",
                                                                                "receiving"
                                                                            ],
                                                                            "description": "What this record is needed for. Null when it is checked but blocks nothing."
                                                                        },
                                                                        "verified": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "message": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What is wrong with the record, when the mail server said. Null is \"no comment\", not \"no problem\"."
                                                                        }
                                                                    }
                                                                },
                                                                "dkim": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "required_for": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "sending",
                                                                                "receiving"
                                                                            ],
                                                                            "description": "What this record is needed for. Null when it is checked but blocks nothing."
                                                                        },
                                                                        "verified": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "message": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What is wrong with the record, when the mail server said. Null is \"no comment\", not \"no problem\"."
                                                                        }
                                                                    }
                                                                },
                                                                "mx": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "required_for": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "sending",
                                                                                "receiving"
                                                                            ],
                                                                            "description": "What this record is needed for. Null when it is checked but blocks nothing."
                                                                        },
                                                                        "verified": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "message": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What is wrong with the record, when the mail server said. Null is \"no comment\", not \"no problem\"."
                                                                        }
                                                                    }
                                                                },
                                                                "dmarc": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "required_for": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "sending",
                                                                                "receiving"
                                                                            ],
                                                                            "description": "What this record is needed for. Null when it is checked but blocks nothing."
                                                                        },
                                                                        "verified": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "message": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What is wrong with the record, when the mail server said. Null is \"no comment\", not \"no problem\"."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "advisory": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "Things worth doing that block nothing, such as publishing DMARC or pointing MX here."
                                                        },
                                                        "checked_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the mail server last resolved these records. Null when it never has, NOT the time of this request."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/verify": {
            "post": {
                "operationId": "postDomainsDomainVerify",
                "summary": "Verify a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain_verification"
                                                            ]
                                                        },
                                                        "domain_id": {
                                                            "type": "string"
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean",
                                                                    "description": "Whether this domain may send. The same value as `sending.enabled` on the domain itself."
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "spf",
                                                                            "dkim"
                                                                        ]
                                                                    },
                                                                    "description": "The records in `checks` that must pass for this verdict. The same list `GET /domains/{domain}` publishes."
                                                                },
                                                                "message": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why this verdict is false, or null when it is true. One record at a time: the first failure, not every failure."
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean",
                                                                    "description": "Whether mail addressed to this domain is delivered here. A send-only domain is expected to be false, and that is not a fault."
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "mx"
                                                                        ]
                                                                    },
                                                                    "description": "The records in `checks` that must pass for this verdict. The same list `GET /domains/{domain}` publishes."
                                                                },
                                                                "message": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why this verdict is false, or null when it is true. One record at a time: the first failure, not every failure."
                                                                }
                                                            }
                                                        },
                                                        "checks": {
                                                            "type": "object",
                                                            "description": "One entry per record, always all four, whether or not the mail server had an answer for it.",
                                                            "properties": {
                                                                "spf": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "required_for": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "sending",
                                                                                "receiving"
                                                                            ],
                                                                            "description": "What this record is needed for. Null when it is checked but blocks nothing."
                                                                        },
                                                                        "verified": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "message": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What is wrong with the record, when the mail server said. Null is \"no comment\", not \"no problem\"."
                                                                        }
                                                                    }
                                                                },
                                                                "dkim": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "required_for": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "sending",
                                                                                "receiving"
                                                                            ],
                                                                            "description": "What this record is needed for. Null when it is checked but blocks nothing."
                                                                        },
                                                                        "verified": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "message": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What is wrong with the record, when the mail server said. Null is \"no comment\", not \"no problem\"."
                                                                        }
                                                                    }
                                                                },
                                                                "mx": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "required_for": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "sending",
                                                                                "receiving"
                                                                            ],
                                                                            "description": "What this record is needed for. Null when it is checked but blocks nothing."
                                                                        },
                                                                        "verified": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "message": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What is wrong with the record, when the mail server said. Null is \"no comment\", not \"no problem\"."
                                                                        }
                                                                    }
                                                                },
                                                                "dmarc": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "required_for": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "sending",
                                                                                "receiving"
                                                                            ],
                                                                            "description": "What this record is needed for. Null when it is checked but blocks nothing."
                                                                        },
                                                                        "verified": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "message": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What is wrong with the record, when the mail server said. Null is \"no comment\", not \"no problem\"."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "advisory": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "Things worth doing that block nothing, such as publishing DMARC or pointing MX here."
                                                        },
                                                        "checked_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the mail server last resolved these records. Null when it never has, NOT the time of this request."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Re-checks this domain's DNS now rather than waiting for the scheduled sweep. Safe to\ncall repeatedly.\n\nDNS propagation is not instant and is not uniform \u2014 a record your own resolver can see\nmay not be visible to ours yet. If verification fails on a record you are certain is\npublished, wait and call again before assuming the value is wrong.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/domains/{domain}/send-records": {
            "post": {
                "operationId": "postDomainsDomainSendRecords",
                "summary": "Email the DNS records to somebody",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "dns_instructions"
                                                            ]
                                                        },
                                                        "sent_to": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "The one address written to, lowercased. This endpoint sends to exactly one recipient and builds the body itself."
                                                        },
                                                        "sent_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the message was accepted for delivery, not when it arrived."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Sends this domain's DNS records to an address \u2014 usually whoever administers the DNS, who is rarely the person holding the API key.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Where to send them."
                                    }
                                }
                            },
                            "example": {
                                "email": "dns-admin@example.com"
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/sync": {
            "post": {
                "operationId": "postDomainsDomainSync",
                "summary": "Sync a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the domain."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note on the domain. Null when none was set."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                }
                                                            }
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Receiving needs MX.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                            "properties": {
                                                                "storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                },
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes this domain may have. The default is 50."
                                                                },
                                                                "mailboxes_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes the domain has now."
                                                                }
                                                            }
                                                        },
                                                        "defaults": {
                                                            "type": "object",
                                                            "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                            "properties": {
                                                                "mailbox_storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/domains/{domain}/enable": {
            "post": {
                "operationId": "postDomainsDomainEnable",
                "summary": "Enable a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the domain."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note on the domain. Null when none was set."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                }
                                                            }
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Receiving needs MX.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                            "properties": {
                                                                "storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                },
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes this domain may have. The default is 50."
                                                                },
                                                                "mailboxes_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes the domain has now."
                                                                }
                                                            }
                                                        },
                                                        "defaults": {
                                                            "type": "object",
                                                            "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                            "properties": {
                                                                "mailbox_storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/domains/{domain}/disable": {
            "post": {
                "operationId": "postDomainsDomainDisable",
                "summary": "Disable a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the domain."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note on the domain. Null when none was set."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                }
                                                            }
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Receiving needs MX.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                            "properties": {
                                                                "storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                },
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes this domain may have. The default is 50."
                                                                },
                                                                "mailboxes_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes the domain has now."
                                                                }
                                                            }
                                                        },
                                                        "defaults": {
                                                            "type": "object",
                                                            "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                            "properties": {
                                                                "mailbox_storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/domains/{domain}/retry-provisioning": {
            "post": {
                "operationId": "postDomainsDomainRetryProvisioning",
                "summary": "Retry Provisioning a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the domain."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The domain itself, e.g. `example.com`."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note on the domain. Null when none was set."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "disabled"
                                                            ],
                                                            "description": "The one lifecycle answer. `disabled` wins over everything: a disabled domain does nothing whatever its provisioning says."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "How far this domain has got on the mail server. This is the detail behind `state`, not a second answer to it: read `state` to decide what a domain can do, and this to explain why.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "Where the domain is in setup on the mail server: `pending`, `provisioning`, `active`, `failed`, `suspended`, `deleting` or `deleted`. For what the domain can do, read `state`."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check `state` or `GET /domains/{domain}/verification-status` before showing it."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "Whether `POST /domains/{domain}/retry-provisioning` would do anything. True exactly when `state` is `failed`."
                                                                }
                                                            }
                                                        },
                                                        "sending": {
                                                            "type": "object",
                                                            "description": "Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "receiving": {
                                                            "type": "object",
                                                            "description": "Receiving needs MX.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "requires": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use `GET /domains/{domain}/limits`.",
                                                            "properties": {
                                                                "storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of mail this domain may store in total. The default is 10 GB."
                                                                },
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes this domain may have. The default is 50."
                                                                },
                                                                "mailboxes_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many mailboxes the domain has now."
                                                                }
                                                            }
                                                        },
                                                        "defaults": {
                                                            "type": "object",
                                                            "description": "What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.",
                                                            "properties": {
                                                                "mailbox_storage_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many bytes of storage each new mailbox gets. The default is 3 GB."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/domains/{domain}/limits": {
            "get": {
                "operationId": "getDomainsDomainLimits",
                "summary": "Limits a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "limits"
                                                            ]
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain",
                                                                "mailbox"
                                                            ],
                                                            "description": "What these limits are about."
                                                        },
                                                        "identifier": {
                                                            "type": "string",
                                                            "description": "The domain name, or the mailbox address."
                                                        },
                                                        "sending_rate": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Sending limits and how much of each is used. Null when the mail server could not be reached.",
                                                            "properties": {
                                                                "limits": {
                                                                    "type": "object",
                                                                    "description": "Messages allowed per window. In each field, 0 means no limit and null means unknown.",
                                                                    "properties": {
                                                                        "hourly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages allowed per hour. 0 means no limit; null means unknown."
                                                                        },
                                                                        "daily": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages allowed per day. 0 means no limit; null means unknown."
                                                                        },
                                                                        "monthly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages allowed per calendar month. 0 means no limit; null means unknown."
                                                                        },
                                                                        "burst": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages allowed per burst. 0 means no limit; null means unknown. This one is configured but not enforced on sends."
                                                                        }
                                                                    }
                                                                },
                                                                "used": {
                                                                    "type": "object",
                                                                    "description": "Messages sent so far in each window. Subtract from `limits` for what is left. Null means unknown.",
                                                                    "properties": {
                                                                        "hourly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages sent this hour. Null means unknown. Do not rely on 0 alone for billing or throttling."
                                                                        },
                                                                        "daily": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages sent today. Null means unknown. Do not rely on 0 alone for billing or throttling."
                                                                        },
                                                                        "monthly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages sent this calendar month. Null means unknown. Do not rely on 0 alone for billing or throttling."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Stored mail. Null when neither usage nor quota could be read.",
                                                            "properties": {
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes stored now. Null means unknown; 0 means empty."
                                                                },
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes allowed. Null with `message_size` present means no limit; null with `message_size` also null means unknown. (Here no limit is null, unlike `sending_rate.limits`, where it is 0.)"
                                                                },
                                                                "messages": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages stored. Null means unknown; 0 means empty."
                                                                }
                                                            }
                                                        },
                                                        "message_size": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Size limits per message, applied at delivery. Null when the mail server could not be reached.",
                                                            "properties": {
                                                                "max_message_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The largest message allowed, in bytes. Null means no limit."
                                                                },
                                                                "max_attachment_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The largest attachment allowed, in bytes. Null means no limit."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/limits/{email}": {
            "get": {
                "operationId": "getDomainsDomainLimitsEmail",
                "summary": "Retrieve sending limits for one address",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "domains:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "email",
                        "in": "path",
                        "required": true,
                        "description": "The email identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "limits"
                                                            ]
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain",
                                                                "mailbox"
                                                            ],
                                                            "description": "What these limits are about."
                                                        },
                                                        "identifier": {
                                                            "type": "string",
                                                            "description": "The domain name, or the mailbox address."
                                                        },
                                                        "sending_rate": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Sending limits and how much of each is used. Null when the mail server could not be reached.",
                                                            "properties": {
                                                                "limits": {
                                                                    "type": "object",
                                                                    "description": "Messages allowed per window. In each field, 0 means no limit and null means unknown.",
                                                                    "properties": {
                                                                        "hourly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages allowed per hour. 0 means no limit; null means unknown."
                                                                        },
                                                                        "daily": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages allowed per day. 0 means no limit; null means unknown."
                                                                        },
                                                                        "monthly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages allowed per calendar month. 0 means no limit; null means unknown."
                                                                        },
                                                                        "burst": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages allowed per burst. 0 means no limit; null means unknown. This one is configured but not enforced on sends."
                                                                        }
                                                                    }
                                                                },
                                                                "used": {
                                                                    "type": "object",
                                                                    "description": "Messages sent so far in each window. Subtract from `limits` for what is left. Null means unknown.",
                                                                    "properties": {
                                                                        "hourly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages sent this hour. Null means unknown. Do not rely on 0 alone for billing or throttling."
                                                                        },
                                                                        "daily": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages sent today. Null means unknown. Do not rely on 0 alone for billing or throttling."
                                                                        },
                                                                        "monthly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Messages sent this calendar month. Null means unknown. Do not rely on 0 alone for billing or throttling."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Stored mail. Null when neither usage nor quota could be read.",
                                                            "properties": {
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes stored now. Null means unknown; 0 means empty."
                                                                },
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes allowed. Null with `message_size` present means no limit; null with `message_size` also null means unknown. (Here no limit is null, unlike `sending_rate.limits`, where it is 0.)"
                                                                },
                                                                "messages": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages stored. Null means unknown; 0 means empty."
                                                                }
                                                            }
                                                        },
                                                        "message_size": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Size limits per message, applied at delivery. Null when the mail server could not be reached.",
                                                            "properties": {
                                                                "max_message_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The largest message allowed, in bytes. Null means no limit."
                                                                },
                                                                "max_attachment_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The largest attachment allowed, in bytes. Null means no limit."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/analytics": {
            "get": {
                "operationId": "getDomainsDomainAnalytics",
                "summary": "Analytics a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain_analytics"
                                                            ]
                                                        },
                                                        "domain_id": {
                                                            "type": "string"
                                                        },
                                                        "period": {
                                                            "type": "object",
                                                            "description": "Defaults to the last 30 days. Both bounds are inclusive.",
                                                            "properties": {
                                                                "start_date": {
                                                                    "type": "string",
                                                                    "format": "date"
                                                                },
                                                                "end_date": {
                                                                    "type": "string",
                                                                    "format": "date"
                                                                }
                                                            }
                                                        },
                                                        "series": {
                                                            "type": "object",
                                                            "properties": {
                                                                "emails_sent": {
                                                                    "type": "array",
                                                                    "description": "Messages accepted for delivery. One point per day in the window, including days with no data.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "date": {
                                                                                "type": "string",
                                                                                "format": "date"
                                                                            },
                                                                            "value": {
                                                                                "type": "number",
                                                                                "nullable": true,
                                                                                "description": "A count, never null: every day in the window is present, and a day with no recorded events is written as 0 rather than left out. Read that 0 as \"nothing was recorded\", not as proof that nothing happened."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "emails_received": {
                                                                    "type": "array",
                                                                    "description": "Messages delivered to this domain. One point per day in the window, including days with no data.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "date": {
                                                                                "type": "string",
                                                                                "format": "date"
                                                                            },
                                                                            "value": {
                                                                                "type": "number",
                                                                                "nullable": true,
                                                                                "description": "A count, never null: every day in the window is present, and a day with no recorded events is written as 0 rather than left out. Read that 0 as \"nothing was recorded\", not as proof that nothing happened."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "delivery_rate": {
                                                                    "type": "array",
                                                                    "description": "Delivered as a share of sent, per day. One point per day in the window, including days with no data.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "date": {
                                                                                "type": "string",
                                                                                "format": "date"
                                                                            },
                                                                            "value": {
                                                                                "type": "number",
                                                                                "nullable": true,
                                                                                "description": "A percentage. Null on a day with no sends."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "bounce_rate": {
                                                                    "type": "array",
                                                                    "description": "Bounced as a share of sent, per day. One point per day in the window, including days with no data.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "date": {
                                                                                "type": "string",
                                                                                "format": "date"
                                                                            },
                                                                            "value": {
                                                                                "type": "number",
                                                                                "nullable": true,
                                                                                "description": "A percentage. Null on a day with no sends."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "spam_complaints": {
                                                                    "type": "array",
                                                                    "description": "Spam reports and delivery complaints. One point per day in the window, including days with no data.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "date": {
                                                                                "type": "string",
                                                                                "format": "date"
                                                                            },
                                                                            "value": {
                                                                                "type": "number",
                                                                                "nullable": true,
                                                                                "description": "A count, never null: every day in the window is present, and a day with no recorded events is written as 0 rather than left out. Read that 0 as \"nothing was recorded\", not as proof that nothing happened."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/health": {
            "get": {
                "operationId": "getDomainsDomainHealth",
                "summary": "Health a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain_health"
                                                            ]
                                                        },
                                                        "domain_id": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "good",
                                                                "warning",
                                                                "critical"
                                                            ],
                                                            "description": "Banded from `score`: good at 90 and above, warning at 60, critical below it."
                                                        },
                                                        "score": {
                                                            "type": "integer",
                                                            "description": "0-100."
                                                        },
                                                        "issues": {
                                                            "type": "array",
                                                            "description": "Every problem found, each with its own fix. Empty when there are none.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "issue": {
                                                                        "type": "string"
                                                                    },
                                                                    "recommendation": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "What to do about this issue."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "metrics": {
                                                            "type": "object",
                                                            "description": "The last 30 days.",
                                                            "properties": {
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages accepted for delivery in the last 30 days. 0 means none are recorded; the rates are then null."
                                                                },
                                                                "delivery_rate": {
                                                                    "type": "number",
                                                                    "nullable": true,
                                                                    "description": "Percentage of sent mail confirmed delivered. Null when nothing was sent in the window."
                                                                },
                                                                "bounce_rate": {
                                                                    "type": "number",
                                                                    "nullable": true,
                                                                    "description": "Percentage of sent mail that bounced. Null when nothing was sent in the window."
                                                                },
                                                                "spam_rate": {
                                                                    "type": "number",
                                                                    "nullable": true,
                                                                    "description": "Percentage of sent mail reported as spam. Null when nothing was sent in the window."
                                                                }
                                                            }
                                                        },
                                                        "checked_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When DNS was last resolved for this domain. Null when it never has been."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/stats": {
            "get": {
                "operationId": "getDomainsDomainStats",
                "summary": "Stats a domain",
                "tags": [
                    "Domains"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "The domain id, or the domain name itself.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain_usage"
                                                            ]
                                                        },
                                                        "domain_id": {
                                                            "type": "string"
                                                        },
                                                        "mailboxes": {
                                                            "type": "object",
                                                            "description": "Counted from the mailbox rows themselves at request time, not from a rollup, so these two are never stale and never unknown.",
                                                            "properties": {
                                                                "total": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Mailboxes on this domain. A live `COUNT`, so it is never null and 0 means the domain genuinely has none."
                                                                },
                                                                "active": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Of those, how many are active. A live `COUNT`, never null; 0 means none are active, which on a domain with mailboxes is a real finding rather than a missing reading."
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "properties": {
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes, summed across this domain's mailboxes. Never null: it is a `SUM` over rows this API owns, and a domain with no mailboxes sums to a genuine 0."
                                                                },
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The storage quota in bytes, as `limits.storage_bytes` on the domain. 0 means no quota is enforced."
                                                                }
                                                            }
                                                        },
                                                        "today": {
                                                            "type": "object",
                                                            "description": "Since midnight UTC.",
                                                            "properties": {
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages accepted for delivery since midnight UTC. Counts can lag a little, so treat this as a minimum and do not bill from it."
                                                                },
                                                                "emails_received": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages delivered to this domain since midnight UTC. Never null, and 0 carries the same caveat as `emails_sent`: it is the absence of recorded events, not measured silence."
                                                                },
                                                                "delivery_rate": {
                                                                    "type": "number",
                                                                    "nullable": true,
                                                                    "description": "A percentage. Null when nothing was sent today."
                                                                },
                                                                "bounce_rate": {
                                                                    "type": "number",
                                                                    "nullable": true,
                                                                    "description": "Percentage. Null when nothing was sent today."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/email-accounts": {
            "get": {
                "operationId": "getEmailAccounts",
                "summary": "List email accounts",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "mailbox"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Unique identifier for the mailbox."
                                                                    },
                                                                    "address": {
                                                                        "type": "string",
                                                                        "description": "The full email address. This *is* the mailbox publicly: there is no separate `username`, because the local part is already in here."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Display name, as it appears to a recipient. null when none was set."
                                                                    },
                                                                    "domain_id": {
                                                                        "type": "string",
                                                                        "description": "The domain this mailbox belongs to. Retrieve it with `GET /api/v1/domains/{domain}`."
                                                                    },
                                                                    "type": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "mail",
                                                                            "smtp",
                                                                            "both"
                                                                        ],
                                                                        "description": "What the mailbox was created as, and what you can filter the list by. Recorded rather than enforced: nothing in the product currently branches on it, so it does not by itself restrict what the mailbox can do."
                                                                    },
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "active",
                                                                            "provisioning",
                                                                            "failed",
                                                                            "suspended",
                                                                            "deleting"
                                                                        ],
                                                                        "description": "Where the mailbox stands: `deleting` first, then `suspended`, then its setup state. Only an `active` mailbox sends and receives."
                                                                    },
                                                                    "provisioning": {
                                                                        "type": "object",
                                                                        "description": "What the mail server has done with this mailbox. Creation is asynchronous, so a mailbox exists here before it exists there.",
                                                                        "properties": {
                                                                            "state": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "pending",
                                                                                    "provisioning",
                                                                                    "active",
                                                                                    "failed",
                                                                                    "suspended",
                                                                                    "deleting",
                                                                                    "deleted"
                                                                                ],
                                                                                "description": "The mailbox's setup state on the mail server. Use the top-level `state` to decide what the mailbox can do."
                                                                            },
                                                                            "error": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Why provisioning failed, in the mail server's words. null unless `state` is `failed`."
                                                                            },
                                                                            "retryable": {
                                                                                "type": "boolean",
                                                                                "description": "True only while `state` is `failed`, which is the only state `POST /retry-provisioning` accepts."
                                                                            }
                                                                        }
                                                                    },
                                                                    "storage": {
                                                                        "type": "object",
                                                                        "description": "Bytes, both of them. Never a pre-formatted \"3 GB\", which cannot be computed with.",
                                                                        "properties": {
                                                                            "quota_bytes": {
                                                                                "type": "integer",
                                                                                "description": "The mailbox's storage limit, in bytes. Always set; the default is 1 GB."
                                                                            },
                                                                            "used_bytes": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "Bytes used. Null means we could not read it yet (for example, the mailbox is not set up on the mail server yet), not that it is empty; show it as unknown."
                                                                            }
                                                                        }
                                                                    },
                                                                    "send_limits": {
                                                                        "type": "object",
                                                                        "description": "Per-mailbox sending overrides.",
                                                                        "properties": {
                                                                            "daily": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "Messages per day for this mailbox. Null means no override, so your plan's limit applies. 0 means it may not send."
                                                                            },
                                                                            "hourly": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "Messages per hour for this mailbox. Null means no override, as with `daily`."
                                                                            }
                                                                        }
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postEmailAccounts",
                "summary": "Create a mailbox",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the mailbox."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "description": "The full email address. This *is* the mailbox publicly: there is no separate `username`, because the local part is already in here."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Display name, as it appears to a recipient. null when none was set."
                                                        },
                                                        "domain_id": {
                                                            "type": "string",
                                                            "description": "The domain this mailbox belongs to. Retrieve it with `GET /api/v1/domains/{domain}`."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mail",
                                                                "smtp",
                                                                "both"
                                                            ],
                                                            "description": "What the mailbox was created as, and what you can filter the list by. Recorded rather than enforced: nothing in the product currently branches on it, so it does not by itself restrict what the mailbox can do."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "suspended",
                                                                "deleting"
                                                            ],
                                                            "description": "Where the mailbox stands: `deleting` first, then `suspended`, then its setup state. Only an `active` mailbox sends and receives."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "What the mail server has done with this mailbox. Creation is asynchronous, so a mailbox exists here before it exists there.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "The mailbox's setup state on the mail server. Use the top-level `state` to decide what the mailbox can do."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why provisioning failed, in the mail server's words. null unless `state` is `failed`."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "True only while `state` is `failed`, which is the only state `POST /retry-provisioning` accepts."
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "description": "Bytes, both of them. Never a pre-formatted \"3 GB\", which cannot be computed with.",
                                                            "properties": {
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "description": "The mailbox's storage limit, in bytes. Always set; the default is 1 GB."
                                                                },
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes used. Null means we could not read it yet (for example, the mailbox is not set up on the mail server yet), not that it is empty; show it as unknown."
                                                                }
                                                            }
                                                        },
                                                        "send_limits": {
                                                            "type": "object",
                                                            "description": "Per-mailbox sending overrides.",
                                                            "properties": {
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per day for this mailbox. Null means no override, so your plan's limit applies. 0 means it may not send."
                                                                },
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per hour for this mailbox. Null means no override, as with `daily`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Creates a real mailbox \u2014 IMAP, SMTP and webmail \u2014 on one of your domains.\n\nThe domain must exist, but it does **not** need to be verified: you will usually want\nmailboxes in place before you cut MX over, not after. Provisioning happens on the mail\nserver and is asynchronous; a mailbox appears with a provisioning status and becomes\nusable when that completes.\n\nPasswords must be at least 12 characters. If you set a forced password change, note it\ngoverns webmail and the mobile apps only \u2014 IMAP and SMTP clients cannot present a\nchange-password prompt, so they keep working with the old password until it is changed\nelsewhere.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain_id": {
                                        "type": "string",
                                        "description": "The ID of one of your domains. Copy it from the domain's page in the dashboard, or read it from `GET /domains`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "The mailbox owner's name. Recipients see it as `Name <address>`.",
                                        "example": "Ada Obi",
                                        "x-example": "Spring newsletter"
                                    },
                                    "username": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The part of the address before the @. On `yourdomain.com`, `ada` makes `ada@yourdomain.com`. Letters, numbers, dots, dashes and underscores.",
                                        "x-example": "ada"
                                    },
                                    "account_type": {
                                        "type": "string",
                                        "enum": [
                                            "mail",
                                            "smtp",
                                            "both"
                                        ],
                                        "description": "Required, but kept for your records only: every mailbox gets full IMAP and SMTP access whatever you send. Send `both`.",
                                        "example": "both"
                                    },
                                    "password": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Optional. At least 12 characters, with letters and numbers. Leave it out and we create a strong one."
                                    },
                                    "must_change_password": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Make the person choose their own password the first time they sign in to webmail or the app. Mail apps (IMAP and SMTP) are not affected.",
                                        "x-example": true
                                    },
                                    "send_setup_to": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "email",
                                        "description": "Optional. An address to email the new mailbox's sign-in details to. It cannot be the new mailbox itself: nobody can open that yet.",
                                        "x-example": "ada.personal@example.com"
                                    },
                                    "storage_quota_mb": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 100000,
                                        "description": "Optional. This mailbox's storage, in megabytes.",
                                        "x-example": 5120
                                    },
                                    "smtp_settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "port": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 65535,
                                                "description": "The port number, like 587 for SMTP or 993 for IMAP."
                                            },
                                            "encryption": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "ssl",
                                                    "tls",
                                                    "none"
                                                ],
                                                "description": "`ssl`, `tls` or `none`."
                                            },
                                            "auth_method": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "plain",
                                                    "login",
                                                    "cram_md5"
                                                ],
                                                "description": "How mail apps sign in: `plain`, `login` or `cram_md5`."
                                            }
                                        },
                                        "description": "Optional. Connection settings to print in the setup email sent to `send_setup_to`. They do not change how the mailbox works."
                                    },
                                    "imap_settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "port": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 65535,
                                                "description": "The port number, like 587 for SMTP or 993 for IMAP."
                                            },
                                            "encryption": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "ssl",
                                                    "tls",
                                                    "none"
                                                ],
                                                "description": "`ssl`, `tls` or `none`."
                                            }
                                        },
                                        "description": "Optional. Connection settings to print in the setup email sent to `send_setup_to`. They do not change how the mailbox works."
                                    }
                                },
                                "required": [
                                    "domain_id",
                                    "name",
                                    "username",
                                    "account_type"
                                ]
                            },
                            "example": {
                                "domain_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                "name": "Ada Obi",
                                "username": "ada",
                                "account_type": "both"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-accounts/bulk-update": {
            "post": {
                "operationId": "postEmailAccountsBulkUpdate",
                "summary": "Bulk Update (email account)",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_bulk_result"
                                                            ]
                                                        },
                                                        "updated": {
                                                            "type": "integer",
                                                            "description": "How many mailboxes were changed."
                                                        },
                                                        "failed": {
                                                            "type": "integer",
                                                            "description": "How many were not. **A bulk update is not atomic**: a 200 with `failed` above zero means part of your batch did not happen, so check this rather than the status code."
                                                        },
                                                        "errors": {
                                                            "type": "array",
                                                            "description": "One entry per failure, and the only place the failures are named. Empty when `failed` is 0.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "mailbox_id": {
                                                                        "type": "string",
                                                                        "description": "The ID of the mailbox that failed, as you sent it in `account_ids`."
                                                                    },
                                                                    "message": {
                                                                        "type": "string",
                                                                        "description": "Why that mailbox was not updated, for a person to read. Do not match on the text."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_ids": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "IDs of the mailboxes to act on. Read them from `GET /email-accounts`.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "suspend",
                                            "activate",
                                            "delete"
                                        ],
                                        "description": "What to do to every mailbox in `account_ids`."
                                    },
                                    "settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "storage_quota_mb": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 100000,
                                                "description": "Optional. This mailbox's storage, in megabytes.",
                                                "x-example": 5120
                                            },
                                            "status": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "active",
                                                    "suspended"
                                                ],
                                                "description": "`active` or `suspended`."
                                            }
                                        },
                                        "description": "Optional. Settings to apply with the action."
                                    }
                                },
                                "required": [
                                    "account_ids",
                                    "action"
                                ]
                            },
                            "example": {
                                "account_ids": [
                                    "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                ],
                                "action": "suspend"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-accounts/{email_account}": {
            "get": {
                "operationId": "getEmailAccountsEmailAccount",
                "summary": "Retrieve a email account",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "email_account",
                        "in": "path",
                        "required": true,
                        "description": "The email account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the mailbox."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "description": "The full email address. This *is* the mailbox publicly: there is no separate `username`, because the local part is already in here."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Display name, as it appears to a recipient. null when none was set."
                                                        },
                                                        "domain_id": {
                                                            "type": "string",
                                                            "description": "The domain this mailbox belongs to. Retrieve it with `GET /api/v1/domains/{domain}`."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mail",
                                                                "smtp",
                                                                "both"
                                                            ],
                                                            "description": "What the mailbox was created as, and what you can filter the list by. Recorded rather than enforced: nothing in the product currently branches on it, so it does not by itself restrict what the mailbox can do."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "suspended",
                                                                "deleting"
                                                            ],
                                                            "description": "Where the mailbox stands: `deleting` first, then `suspended`, then its setup state. Only an `active` mailbox sends and receives."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "What the mail server has done with this mailbox. Creation is asynchronous, so a mailbox exists here before it exists there.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "The mailbox's setup state on the mail server. Use the top-level `state` to decide what the mailbox can do."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why provisioning failed, in the mail server's words. null unless `state` is `failed`."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "True only while `state` is `failed`, which is the only state `POST /retry-provisioning` accepts."
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "description": "Bytes, both of them. Never a pre-formatted \"3 GB\", which cannot be computed with.",
                                                            "properties": {
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "description": "The mailbox's storage limit, in bytes. Always set; the default is 1 GB."
                                                                },
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes used. Null means we could not read it yet (for example, the mailbox is not set up on the mail server yet), not that it is empty; show it as unknown."
                                                                }
                                                            }
                                                        },
                                                        "send_limits": {
                                                            "type": "object",
                                                            "description": "Per-mailbox sending overrides.",
                                                            "properties": {
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per day for this mailbox. Null means no override, so your plan's limit applies. 0 means it may not send."
                                                                },
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per hour for this mailbox. Null means no override, as with `daily`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putEmailAccountsEmailAccount",
                "summary": "Update a email account",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "email_account",
                        "in": "path",
                        "required": true,
                        "description": "The email account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the mailbox."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "description": "The full email address. This *is* the mailbox publicly: there is no separate `username`, because the local part is already in here."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Display name, as it appears to a recipient. null when none was set."
                                                        },
                                                        "domain_id": {
                                                            "type": "string",
                                                            "description": "The domain this mailbox belongs to. Retrieve it with `GET /api/v1/domains/{domain}`."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mail",
                                                                "smtp",
                                                                "both"
                                                            ],
                                                            "description": "What the mailbox was created as, and what you can filter the list by. Recorded rather than enforced: nothing in the product currently branches on it, so it does not by itself restrict what the mailbox can do."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "suspended",
                                                                "deleting"
                                                            ],
                                                            "description": "Where the mailbox stands: `deleting` first, then `suspended`, then its setup state. Only an `active` mailbox sends and receives."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "What the mail server has done with this mailbox. Creation is asynchronous, so a mailbox exists here before it exists there.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "The mailbox's setup state on the mail server. Use the top-level `state` to decide what the mailbox can do."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why provisioning failed, in the mail server's words. null unless `state` is `failed`."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "True only while `state` is `failed`, which is the only state `POST /retry-provisioning` accepts."
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "description": "Bytes, both of them. Never a pre-formatted \"3 GB\", which cannot be computed with.",
                                                            "properties": {
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "description": "The mailbox's storage limit, in bytes. Always set; the default is 1 GB."
                                                                },
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes used. Null means we could not read it yet (for example, the mailbox is not set up on the mail server yet), not that it is empty; show it as unknown."
                                                                }
                                                            }
                                                        },
                                                        "send_limits": {
                                                            "type": "object",
                                                            "description": "Per-mailbox sending overrides.",
                                                            "properties": {
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per day for this mailbox. Null means no override, so your plan's limit applies. 0 means it may not send."
                                                                },
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per hour for this mailbox. Null means no override, as with `daily`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The mailbox owner's name. Recipients see it as `Name <address>`.",
                                        "example": "Ada Obi",
                                        "x-example": "Spring newsletter"
                                    },
                                    "storage_quota_mb": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 100000,
                                        "description": "Optional. This mailbox's storage, in megabytes.",
                                        "x-example": 5120
                                    },
                                    "account_type": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "mail",
                                            "smtp",
                                            "both"
                                        ],
                                        "description": "Kept for your records only: every mailbox has full IMAP and SMTP access, whatever this says."
                                    },
                                    "status": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "Active",
                                            "Inactive"
                                        ],
                                        "description": "`Inactive` stops the mailbox signing in and receiving; `Active` turns it back on."
                                    },
                                    "smtp_settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "port": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 65535,
                                                "description": "The port number, like 587 for SMTP or 993 for IMAP."
                                            },
                                            "encryption": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "ssl",
                                                    "tls",
                                                    "none"
                                                ],
                                                "description": "`ssl`, `tls` or `none`."
                                            },
                                            "auth_method": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "plain",
                                                    "login",
                                                    "cram_md5"
                                                ],
                                                "description": "How mail apps sign in: `plain`, `login` or `cram_md5`."
                                            }
                                        },
                                        "description": "Optional. Connection settings to print in the setup email sent to `send_setup_to`. They do not change how the mailbox works."
                                    },
                                    "imap_settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "port": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 65535,
                                                "description": "The port number, like 587 for SMTP or 993 for IMAP."
                                            },
                                            "encryption": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "ssl",
                                                    "tls",
                                                    "none"
                                                ],
                                                "description": "`ssl`, `tls` or `none`."
                                            }
                                        },
                                        "description": "Optional. Connection settings to print in the setup email sent to `send_setup_to`. They do not change how the mailbox works."
                                    }
                                }
                            },
                            "example": {
                                "name": "Ada Obi"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            },
            "patch": {
                "operationId": "patchEmailAccountsEmailAccount",
                "summary": "Update a email account",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "email_account",
                        "in": "path",
                        "required": true,
                        "description": "The email account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the mailbox."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "description": "The full email address. This *is* the mailbox publicly: there is no separate `username`, because the local part is already in here."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Display name, as it appears to a recipient. null when none was set."
                                                        },
                                                        "domain_id": {
                                                            "type": "string",
                                                            "description": "The domain this mailbox belongs to. Retrieve it with `GET /api/v1/domains/{domain}`."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mail",
                                                                "smtp",
                                                                "both"
                                                            ],
                                                            "description": "What the mailbox was created as, and what you can filter the list by. Recorded rather than enforced: nothing in the product currently branches on it, so it does not by itself restrict what the mailbox can do."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "suspended",
                                                                "deleting"
                                                            ],
                                                            "description": "Where the mailbox stands: `deleting` first, then `suspended`, then its setup state. Only an `active` mailbox sends and receives."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "What the mail server has done with this mailbox. Creation is asynchronous, so a mailbox exists here before it exists there.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "The mailbox's setup state on the mail server. Use the top-level `state` to decide what the mailbox can do."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why provisioning failed, in the mail server's words. null unless `state` is `failed`."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "True only while `state` is `failed`, which is the only state `POST /retry-provisioning` accepts."
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "description": "Bytes, both of them. Never a pre-formatted \"3 GB\", which cannot be computed with.",
                                                            "properties": {
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "description": "The mailbox's storage limit, in bytes. Always set; the default is 1 GB."
                                                                },
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes used. Null means we could not read it yet (for example, the mailbox is not set up on the mail server yet), not that it is empty; show it as unknown."
                                                                }
                                                            }
                                                        },
                                                        "send_limits": {
                                                            "type": "object",
                                                            "description": "Per-mailbox sending overrides.",
                                                            "properties": {
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per day for this mailbox. Null means no override, so your plan's limit applies. 0 means it may not send."
                                                                },
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per hour for this mailbox. Null means no override, as with `daily`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The mailbox owner's name. Recipients see it as `Name <address>`.",
                                        "example": "Ada Obi",
                                        "x-example": "Spring newsletter"
                                    },
                                    "storage_quota_mb": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 100000,
                                        "description": "Optional. This mailbox's storage, in megabytes.",
                                        "x-example": 5120
                                    },
                                    "account_type": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "mail",
                                            "smtp",
                                            "both"
                                        ],
                                        "description": "Kept for your records only: every mailbox has full IMAP and SMTP access, whatever this says."
                                    },
                                    "status": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "Active",
                                            "Inactive"
                                        ],
                                        "description": "`Inactive` stops the mailbox signing in and receiving; `Active` turns it back on."
                                    },
                                    "smtp_settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "port": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 65535,
                                                "description": "The port number, like 587 for SMTP or 993 for IMAP."
                                            },
                                            "encryption": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "ssl",
                                                    "tls",
                                                    "none"
                                                ],
                                                "description": "`ssl`, `tls` or `none`."
                                            },
                                            "auth_method": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "plain",
                                                    "login",
                                                    "cram_md5"
                                                ],
                                                "description": "How mail apps sign in: `plain`, `login` or `cram_md5`."
                                            }
                                        },
                                        "description": "Optional. Connection settings to print in the setup email sent to `send_setup_to`. They do not change how the mailbox works."
                                    },
                                    "imap_settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "port": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 65535,
                                                "description": "The port number, like 587 for SMTP or 993 for IMAP."
                                            },
                                            "encryption": {
                                                "nullable": true,
                                                "type": "string",
                                                "enum": [
                                                    "ssl",
                                                    "tls",
                                                    "none"
                                                ],
                                                "description": "`ssl`, `tls` or `none`."
                                            }
                                        },
                                        "description": "Optional. Connection settings to print in the setup email sent to `send_setup_to`. They do not change how the mailbox works."
                                    }
                                }
                            },
                            "example": {
                                "name": "Ada Obi"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteEmailAccountsEmailAccount",
                "summary": "Delete a email account",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "email_account",
                        "in": "path",
                        "required": true,
                        "description": "The email account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "Nothing; `message` confirms the deletion. The mailbox reads `deleting` for a short while before it is gone. Its mail is deleted with it, and this cannot be undone."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/email-accounts/{account}/overview": {
            "get": {
                "operationId": "getEmailAccountsAccountOverview",
                "summary": "Overview a email account",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the mailbox."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "description": "The full email address. This *is* the mailbox publicly: there is no separate `username`, because the local part is already in here."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Display name, as it appears to a recipient. null when none was set."
                                                        },
                                                        "domain_id": {
                                                            "type": "string",
                                                            "description": "The domain this mailbox belongs to. Retrieve it with `GET /api/v1/domains/{domain}`."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mail",
                                                                "smtp",
                                                                "both"
                                                            ],
                                                            "description": "What the mailbox was created as, and what you can filter the list by. Recorded rather than enforced: nothing in the product currently branches on it, so it does not by itself restrict what the mailbox can do."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "suspended",
                                                                "deleting"
                                                            ],
                                                            "description": "Where the mailbox stands: `deleting` first, then `suspended`, then its setup state. Only an `active` mailbox sends and receives."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "What the mail server has done with this mailbox. Creation is asynchronous, so a mailbox exists here before it exists there.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "The mailbox's setup state on the mail server. Use the top-level `state` to decide what the mailbox can do."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why provisioning failed, in the mail server's words. null unless `state` is `failed`."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "True only while `state` is `failed`, which is the only state `POST /retry-provisioning` accepts."
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "description": "Bytes, both of them. Never a pre-formatted \"3 GB\", which cannot be computed with.",
                                                            "properties": {
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "description": "The mailbox's storage limit, in bytes. Always set; the default is 1 GB."
                                                                },
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes used. Null means we could not read it yet (for example, the mailbox is not set up on the mail server yet), not that it is empty; show it as unknown."
                                                                }
                                                            }
                                                        },
                                                        "send_limits": {
                                                            "type": "object",
                                                            "description": "Per-mailbox sending overrides.",
                                                            "properties": {
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per day for this mailbox. Null means no override, so your plan's limit applies. 0 means it may not send."
                                                                },
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per hour for this mailbox. Null means no override, as with `daily`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/email-accounts/{account}/stats": {
            "get": {
                "operationId": "getEmailAccountsAccountStats",
                "summary": "Stats a email account",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_stats"
                                                            ]
                                                        },
                                                        "mailbox_id": {
                                                            "type": "string",
                                                            "description": "The mailbox these counters describe. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                        },
                                                        "messages": {
                                                            "type": "object",
                                                            "description": "Five independent answers about one set of messages. **`total` is not `sent` + `received`**: a message can be counted in both `unread` and `starred`, and `total` counts rows. Do not expect these to add up.",
                                                            "properties": {
                                                                "total": {
                                                                    "type": "integer"
                                                                },
                                                                "sent": {
                                                                    "type": "integer"
                                                                },
                                                                "received": {
                                                                    "type": "integer"
                                                                },
                                                                "unread": {
                                                                    "type": "integer"
                                                                },
                                                                "starred": {
                                                                    "type": "integer"
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "description": "Storage in bytes, as `storage` on the mailbox. For a percentage, divide `used_bytes` by `quota_bytes`.",
                                                            "properties": {
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "description": "The mailbox's storage limit, in bytes. Always set."
                                                                },
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes used. Null means we could not read it yet, not that the mailbox is empty."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/email-accounts/{account}/retry-provisioning": {
            "post": {
                "operationId": "postEmailAccountsAccountRetryProvisioning",
                "summary": "Retry provisioning a mailbox",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the mailbox."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "description": "The full email address. This *is* the mailbox publicly: there is no separate `username`, because the local part is already in here."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Display name, as it appears to a recipient. null when none was set."
                                                        },
                                                        "domain_id": {
                                                            "type": "string",
                                                            "description": "The domain this mailbox belongs to. Retrieve it with `GET /api/v1/domains/{domain}`."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mail",
                                                                "smtp",
                                                                "both"
                                                            ],
                                                            "description": "What the mailbox was created as, and what you can filter the list by. Recorded rather than enforced: nothing in the product currently branches on it, so it does not by itself restrict what the mailbox can do."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "suspended",
                                                                "deleting"
                                                            ],
                                                            "description": "Where the mailbox stands: `deleting` first, then `suspended`, then its setup state. Only an `active` mailbox sends and receives."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "What the mail server has done with this mailbox. Creation is asynchronous, so a mailbox exists here before it exists there.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "The mailbox's setup state on the mail server. Use the top-level `state` to decide what the mailbox can do."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why provisioning failed, in the mail server's words. null unless `state` is `failed`."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "True only while `state` is `failed`, which is the only state `POST /retry-provisioning` accepts."
                                                                }
                                                            }
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "description": "Bytes, both of them. Never a pre-formatted \"3 GB\", which cannot be computed with.",
                                                            "properties": {
                                                                "quota_bytes": {
                                                                    "type": "integer",
                                                                    "description": "The mailbox's storage limit, in bytes. Always set; the default is 1 GB."
                                                                },
                                                                "used_bytes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Bytes used. Null means we could not read it yet (for example, the mailbox is not set up on the mail server yet), not that it is empty; show it as unknown."
                                                                }
                                                            }
                                                        },
                                                        "send_limits": {
                                                            "type": "object",
                                                            "description": "Per-mailbox sending overrides.",
                                                            "properties": {
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per day for this mailbox. Null means no override, so your plan's limit applies. 0 means it may not send."
                                                                },
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages per hour for this mailbox. Null means no override, as with `daily`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/email-accounts/{account}/reset-password": {
            "post": {
                "operationId": "postEmailAccountsAccountResetPassword",
                "summary": "Reset Password a email account",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_password"
                                                            ]
                                                        },
                                                        "mailbox_id": {
                                                            "type": "string",
                                                            "description": "The mailbox whose password changed. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                        },
                                                        "password": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The new password, from `POST /generate-password`. **It is shown only once, here**: save it now, because it can never be read again. Null from `POST /reset-password`, where you chose the password yourself."
                                                        },
                                                        "changed_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the password was changed, which is the time of this request."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "new_password": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The new password: at least 12 characters, with letters and numbers."
                                    },
                                    "must_change_password": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Make the person choose their own password at their next sign-in to webmail or the app.",
                                        "x-example": true
                                    },
                                    "send_to": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "Optional. An address to email the new password to. Not the mailbox itself: its owner cannot sign in to read it.",
                                        "x-example": "ada.personal@example.com"
                                    }
                                },
                                "required": [
                                    "new_password"
                                ]
                            },
                            "example": {
                                "new_password": "new_password"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-accounts/{account}/generate-password": {
            "post": {
                "operationId": "postEmailAccountsAccountGeneratePassword",
                "summary": "Generate Password a email account",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_password"
                                                            ]
                                                        },
                                                        "mailbox_id": {
                                                            "type": "string",
                                                            "description": "The mailbox whose password changed. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                        },
                                                        "password": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The new password, from `POST /generate-password`. **It is shown only once, here**: save it now, because it can never be read again. Null from `POST /reset-password`, where you chose the password yourself."
                                                        },
                                                        "changed_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the password was changed, which is the time of this request."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "length": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 8,
                                        "maximum": 64,
                                        "description": "How many characters the generated password has.",
                                        "x-example": 16
                                    },
                                    "include_symbols": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Whether the generated password may contain symbols.",
                                        "x-example": true
                                    },
                                    "must_change_password": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Make the person choose their own password at their next sign-in to webmail or the app.",
                                        "x-example": true
                                    },
                                    "send_to": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "Optional. An address to email the new password to. Not the mailbox itself: its owner cannot sign in to read it.",
                                        "x-example": "ada.personal@example.com"
                                    }
                                }
                            },
                            "example": {
                                "length": 16,
                                "include_symbols": true
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-accounts/{account}/aliases": {
            "get": {
                "operationId": "getEmailAccountsAccountAliases",
                "summary": "List a mailbox's aliases",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "mailbox_alias"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "description": "Unique identifier for the alias."
                                                            },
                                                            "mailbox_id": {
                                                                "type": "string",
                                                                "description": "The mailbox this alias delivers into. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                            },
                                                            "address": {
                                                                "type": "string",
                                                                "description": "The additional address. An alias **receives only** \u2014 it cannot be used as an SMTP login, and mail sent through it still leaves as the mailbox."
                                                            },
                                                            "state": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "active",
                                                                    "provisioning",
                                                                    "failed",
                                                                    "suspended",
                                                                    "deleting"
                                                                ],
                                                                "description": "The same closed set, and the same ordering, as a mailbox `state`, so one branch in your code handles both. Only an `active` alias routes mail."
                                                            },
                                                            "provisioning": {
                                                                "type": "object",
                                                                "description": "What the mail server has done with this alias. Creation is asynchronous, so an alias exists here before it routes anything there.",
                                                                "properties": {
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "pending",
                                                                            "provisioning",
                                                                            "active",
                                                                            "failed",
                                                                            "suspended",
                                                                            "deleting",
                                                                            "deleted"
                                                                        ],
                                                                        "description": "The alias's setup state on the mail server, with the same values as a mailbox's `provisioning.state`. `provisioning.error` names any failure."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why provisioning failed. null unless `state` is `failed`."
                                                                    },
                                                                    "retryable": {
                                                                        "type": "boolean",
                                                                        "description": "True only while `state` is `failed`, which is the only state `POST /aliases/{alias}/retry-provisioning` accepts."
                                                                    }
                                                                }
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            },
                                                            "updated_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postEmailAccountsAccountAliases",
                "summary": "Add an alias",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_alias"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the alias."
                                                        },
                                                        "mailbox_id": {
                                                            "type": "string",
                                                            "description": "The mailbox this alias delivers into. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "description": "The additional address. An alias **receives only** \u2014 it cannot be used as an SMTP login, and mail sent through it still leaves as the mailbox."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "suspended",
                                                                "deleting"
                                                            ],
                                                            "description": "The same closed set, and the same ordering, as a mailbox `state`, so one branch in your code handles both. Only an `active` alias routes mail."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "What the mail server has done with this alias. Creation is asynchronous, so an alias exists here before it routes anything there.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "The alias's setup state on the mail server, with the same values as a mailbox's `provisioning.state`. `provisioning.error` names any failure."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why provisioning failed. null unless `state` is `failed`."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "True only while `state` is `failed`, which is the only state `POST /aliases/{alias}/retry-provisioning` accepts."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "An additional address delivering into this mailbox. Aliases cannot be used as SMTP logins; they receive only.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email_account_id": {
                                        "type": "string",
                                        "description": "The mailbox the alias delivers to: the same ID as in the path.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "alias_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "The extra address, on one of your domains, whose mail is delivered to this mailbox.",
                                        "x-example": "sales@yourdomain.com"
                                    },
                                    "is_active": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Whether it is switched on. Defaults to true.",
                                        "x-example": true
                                    }
                                },
                                "required": [
                                    "email_account_id",
                                    "alias_email"
                                ]
                            },
                            "example": {
                                "email_account_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                "alias_email": "sales@yourdomain.com"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-accounts/{account}/aliases/{alias}": {
            "delete": {
                "operationId": "deleteEmailAccountsAccountAliasesAlias",
                "summary": "Delete a mailbox alias",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "alias",
                        "in": "path",
                        "required": true,
                        "description": "The alias identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content; `message` confirms the deletion. An alias that reached the mail server is removed there first and stops routing once that completes, which is asynchronous."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/email-accounts/{account}/aliases/{alias}/retry-provisioning": {
            "post": {
                "operationId": "postEmailAccountsAccountAliasesAliasRetryProvisioning",
                "summary": "Retry provisioning an alias",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "alias",
                        "in": "path",
                        "required": true,
                        "description": "The alias identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_alias"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the alias."
                                                        },
                                                        "mailbox_id": {
                                                            "type": "string",
                                                            "description": "The mailbox this alias delivers into. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "description": "The additional address. An alias **receives only** \u2014 it cannot be used as an SMTP login, and mail sent through it still leaves as the mailbox."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "provisioning",
                                                                "failed",
                                                                "suspended",
                                                                "deleting"
                                                            ],
                                                            "description": "The same closed set, and the same ordering, as a mailbox `state`, so one branch in your code handles both. Only an `active` alias routes mail."
                                                        },
                                                        "provisioning": {
                                                            "type": "object",
                                                            "description": "What the mail server has done with this alias. Creation is asynchronous, so an alias exists here before it routes anything there.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "provisioning",
                                                                        "active",
                                                                        "failed",
                                                                        "suspended",
                                                                        "deleting",
                                                                        "deleted"
                                                                    ],
                                                                    "description": "The alias's setup state on the mail server, with the same values as a mailbox's `provisioning.state`. `provisioning.error` names any failure."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why provisioning failed. null unless `state` is `failed`."
                                                                },
                                                                "retryable": {
                                                                    "type": "boolean",
                                                                    "description": "True only while `state` is `failed`, which is the only state `POST /aliases/{alias}/retry-provisioning` accepts."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/email-accounts/{account}/forwarding-rules": {
            "get": {
                "operationId": "getEmailAccountsAccountForwardingRules",
                "summary": "List forwarding rules",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "mailbox_forwarding_rule"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "description": "Unique identifier for the rule."
                                                            },
                                                            "mailbox_id": {
                                                                "type": "string",
                                                                "description": "The mailbox this rule applies to. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                            },
                                                            "forward_to": {
                                                                "type": "string",
                                                                "description": "The address mail is forwarded to."
                                                            },
                                                            "condition": {
                                                                "type": "object",
                                                                "description": "When the rule applies. The two halves travel together because they are meaningless apart.",
                                                                "properties": {
                                                                    "type": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "all",
                                                                            "from",
                                                                            "subject",
                                                                            "has_attachment"
                                                                        ],
                                                                        "description": "`all` forwards everything; `from` and `subject` match `value`; `has_attachment` needs no value."
                                                                    },
                                                                    "value": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The address or subject fragment matched on. **null when `type` is `all` or `has_attachment`**, where there is nothing to match against \u2014 not an unknown value."
                                                                    }
                                                                }
                                                            },
                                                            "keep_copy": {
                                                                "type": "boolean",
                                                                "description": "Whether the original is also left in the mailbox. False forwards and removes."
                                                            },
                                                            "active": {
                                                                "type": "boolean",
                                                                "description": "Whether the rule is switched on."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            },
                                                            "updated_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postEmailAccountsAccountForwardingRules",
                "summary": "Create a forwarding rule",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_forwarding_rule"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the rule."
                                                        },
                                                        "mailbox_id": {
                                                            "type": "string",
                                                            "description": "The mailbox this rule applies to. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                        },
                                                        "forward_to": {
                                                            "type": "string",
                                                            "description": "The address mail is forwarded to."
                                                        },
                                                        "condition": {
                                                            "type": "object",
                                                            "description": "When the rule applies. The two halves travel together because they are meaningless apart.",
                                                            "properties": {
                                                                "type": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "all",
                                                                        "from",
                                                                        "subject",
                                                                        "has_attachment"
                                                                    ],
                                                                    "description": "`all` forwards everything; `from` and `subject` match `value`; `has_attachment` needs no value."
                                                                },
                                                                "value": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The address or subject fragment matched on. **null when `type` is `all` or `has_attachment`**, where there is nothing to match against \u2014 not an unknown value."
                                                                }
                                                            }
                                                        },
                                                        "keep_copy": {
                                                            "type": "boolean",
                                                            "description": "Whether the original is also left in the mailbox. False forwards and removes."
                                                        },
                                                        "active": {
                                                            "type": "boolean",
                                                            "description": "Whether the rule is switched on."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email_account_id": {
                                        "type": "string",
                                        "description": "The mailbox whose mail is forwarded: the same ID as in the path.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "forward_to_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "Where to forward the mail.",
                                        "x-example": "ada.personal@example.com"
                                    },
                                    "condition_type": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "from",
                                            "subject",
                                            "has_attachment"
                                        ],
                                        "description": "Which mail to forward: `all` of it, or only mail whose `from` or `subject` contains `condition_value`, or mail that `has_attachment`.",
                                        "x-example": "all"
                                    },
                                    "condition_value": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The text to look for when `condition_type` is `from` or `subject`."
                                    },
                                    "is_active": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Whether it is switched on. Defaults to true.",
                                        "x-example": true
                                    },
                                    "keep_copy": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Also keep the mail in this mailbox, not only forward it.",
                                        "x-example": true
                                    }
                                },
                                "required": [
                                    "email_account_id",
                                    "forward_to_email"
                                ]
                            },
                            "example": {
                                "email_account_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                "forward_to_email": "ada.personal@example.com"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-accounts/{account}/forwarding-rules/{rule}": {
            "put": {
                "operationId": "putEmailAccountsAccountForwardingRulesRule",
                "summary": "Update a forwarding rule",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "rule",
                        "in": "path",
                        "required": true,
                        "description": "The rule identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_forwarding_rule"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the rule."
                                                        },
                                                        "mailbox_id": {
                                                            "type": "string",
                                                            "description": "The mailbox this rule applies to. Retrieve it with `GET /api/v1/email-accounts/{email_account}`."
                                                        },
                                                        "forward_to": {
                                                            "type": "string",
                                                            "description": "The address mail is forwarded to."
                                                        },
                                                        "condition": {
                                                            "type": "object",
                                                            "description": "When the rule applies. The two halves travel together because they are meaningless apart.",
                                                            "properties": {
                                                                "type": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "all",
                                                                        "from",
                                                                        "subject",
                                                                        "has_attachment"
                                                                    ],
                                                                    "description": "`all` forwards everything; `from` and `subject` match `value`; `has_attachment` needs no value."
                                                                },
                                                                "value": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The address or subject fragment matched on. **null when `type` is `all` or `has_attachment`**, where there is nothing to match against \u2014 not an unknown value."
                                                                }
                                                            }
                                                        },
                                                        "keep_copy": {
                                                            "type": "boolean",
                                                            "description": "Whether the original is also left in the mailbox. False forwards and removes."
                                                        },
                                                        "active": {
                                                            "type": "boolean",
                                                            "description": "Whether the rule is switched on."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "forward_to_email": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "Where to forward the mail.",
                                        "x-example": "ada.personal@example.com"
                                    },
                                    "condition_type": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "from",
                                            "subject",
                                            "has_attachment"
                                        ],
                                        "description": "Which mail to forward: `all` of it, or only mail whose `from` or `subject` contains `condition_value`, or mail that `has_attachment`.",
                                        "x-example": "all"
                                    },
                                    "condition_value": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The text to look for when `condition_type` is `from` or `subject`."
                                    },
                                    "is_active": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Whether it is switched on. Defaults to true.",
                                        "x-example": true
                                    },
                                    "keep_copy": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Also keep the mail in this mailbox, not only forward it.",
                                        "x-example": true
                                    }
                                }
                            },
                            "example": {
                                "forward_to_email": "ada.personal@example.com",
                                "condition_type": "all"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteEmailAccountsAccountForwardingRulesRule",
                "summary": "Delete a forwarding rule",
                "tags": [
                    "Mailboxes"
                ],
                "x-required-scope": "mailboxes:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "description": "The account identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "rule",
                        "in": "path",
                        "required": true,
                        "description": "The rule identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content; `message` confirms the deletion. The rule is removed immediately and completely."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/senders": {
            "get": {
                "operationId": "getSenders",
                "summary": "List senders",
                "tags": [
                    "Senders"
                ],
                "x-required-scope": "senders:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "sender"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Unique identifier for the sender."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The display name recipients see, e.g. `Acme Support` in `Acme Support <hello@acme.com>`."
                                                                    },
                                                                    "email": {
                                                                        "type": "string",
                                                                        "format": "email",
                                                                        "description": "The address this identity sends as. `POST /messages` refuses a `from` that is not a verified sender."
                                                                    },
                                                                    "domain": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The domain this address sends from, such as `acme.com`. Its DNS details are on `GET /domains/{domain}`."
                                                                    },
                                                                    "verification": {
                                                                        "type": "object",
                                                                        "description": "Whether this address may be sent from. Verification checks the domain's public DNS records; there is no token.",
                                                                        "properties": {
                                                                            "state": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "pending",
                                                                                    "verified",
                                                                                    "failed"
                                                                                ],
                                                                                "description": "The one verification answer. Only `verified` permits sending; `pending` and `failed` both do not, and differ in whether a check has run."
                                                                            },
                                                                            "verified_at": {
                                                                                "type": "string",
                                                                                "format": "date-time",
                                                                                "nullable": true,
                                                                                "description": "When the address last passed verification. Set only while `state` is `verified`. Read `state` to know whether the sender works."
                                                                            },
                                                                            "error": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Why the last check failed, usually DNS records still missing. Null when `state` is not `failed`."
                                                                            }
                                                                        }
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When this sender was created."
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When this sender was last changed."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postSenders",
                "summary": "Add a sending identity",
                "tags": [
                    "Senders"
                ],
                "x-required-scope": "senders:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "sender"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the sender."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The display name recipients see, e.g. `Acme Support` in `Acme Support <hello@acme.com>`."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "The address this identity sends as. `POST /messages` refuses a `from` that is not a verified sender."
                                                        },
                                                        "domain": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The domain this address sends from, such as `acme.com`. Its DNS details are on `GET /domains/{domain}`."
                                                        },
                                                        "verification": {
                                                            "type": "object",
                                                            "description": "Whether this address may be sent from. Verification checks the domain's public DNS records; there is no token.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "verified",
                                                                        "failed"
                                                                    ],
                                                                    "description": "The one verification answer. Only `verified` permits sending; `pending` and `failed` both do not, and differ in whether a check has run."
                                                                },
                                                                "verified_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the address last passed verification. Set only while `state` is `verified`. Read `state` to know whether the sender works."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why the last check failed, usually DNS records still missing. Null when `state` is not `failed`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this sender was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this sender was last changed."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "A sender is an identity you are allowed to send *as* \u2014 a name and address, like\n`Ada from Acme <ada@acme.com>`.\n\nThis is not the same as a mailbox, and not the same as an SMTP credential. A mailbox\nreceives; a credential authenticates; a sender is what appears in the `From:` header.\n`POST /messages` refuses a `from` address that is not a verified sender here.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain_id": {
                                        "type": "string",
                                        "description": "The ID of one of your domains. Copy it from the domain's page in the dashboard, or read it from `GET /domains`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The name recipients see next to the address, as in `Ada from Acme <ada@yourdomain.com>`.",
                                        "example": "Ada from Acme",
                                        "x-example": "Spring newsletter"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "The From address, on the domain `domain_id`.",
                                        "example": "ada@yourdomain.com"
                                    },
                                    "email_account_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. The mailbox this address belongs to, when it is one of your Mailyte mailboxes. Copy its ID from the mailbox's page, or read it from `GET /email-accounts`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    }
                                },
                                "required": [
                                    "domain_id",
                                    "name",
                                    "email"
                                ]
                            },
                            "example": {
                                "domain_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                "name": "Ada from Acme",
                                "email": "ada@yourdomain.com"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/senders/{sender}": {
            "get": {
                "operationId": "getSendersSender",
                "summary": "Retrieve a sender",
                "tags": [
                    "Senders"
                ],
                "x-required-scope": "senders:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "sender",
                        "in": "path",
                        "required": true,
                        "description": "The sender identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "sender"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the sender."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The display name recipients see, e.g. `Acme Support` in `Acme Support <hello@acme.com>`."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "The address this identity sends as. `POST /messages` refuses a `from` that is not a verified sender."
                                                        },
                                                        "domain": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The domain this address sends from, such as `acme.com`. Its DNS details are on `GET /domains/{domain}`."
                                                        },
                                                        "verification": {
                                                            "type": "object",
                                                            "description": "Whether this address may be sent from. Verification checks the domain's public DNS records; there is no token.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "verified",
                                                                        "failed"
                                                                    ],
                                                                    "description": "The one verification answer. Only `verified` permits sending; `pending` and `failed` both do not, and differ in whether a check has run."
                                                                },
                                                                "verified_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the address last passed verification. Set only while `state` is `verified`. Read `state` to know whether the sender works."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why the last check failed, usually DNS records still missing. Null when `state` is not `failed`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this sender was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this sender was last changed."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putSendersSender",
                "summary": "Update a sender",
                "tags": [
                    "Senders"
                ],
                "x-required-scope": "senders:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "sender",
                        "in": "path",
                        "required": true,
                        "description": "The sender identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "sender"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the sender."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The display name recipients see, e.g. `Acme Support` in `Acme Support <hello@acme.com>`."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "The address this identity sends as. `POST /messages` refuses a `from` that is not a verified sender."
                                                        },
                                                        "domain": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The domain this address sends from, such as `acme.com`. Its DNS details are on `GET /domains/{domain}`."
                                                        },
                                                        "verification": {
                                                            "type": "object",
                                                            "description": "Whether this address may be sent from. Verification checks the domain's public DNS records; there is no token.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "verified",
                                                                        "failed"
                                                                    ],
                                                                    "description": "The one verification answer. Only `verified` permits sending; `pending` and `failed` both do not, and differ in whether a check has run."
                                                                },
                                                                "verified_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the address last passed verification. Set only while `state` is `verified`. Read `state` to know whether the sender works."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why the last check failed, usually DNS records still missing. Null when `state` is not `failed`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this sender was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this sender was last changed."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain_id": {
                                        "type": "string",
                                        "description": "The ID of one of your domains. Copy it from the domain's page in the dashboard, or read it from `GET /domains`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "email_account_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. The mailbox this address belongs to, when it is one of your Mailyte mailboxes. Copy its ID from the mailbox's page, or read it from `GET /email-accounts`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The name recipients see next to the address, as in `Ada from Acme <ada@yourdomain.com>`.",
                                        "example": "Ada from Acme",
                                        "x-example": "Spring newsletter"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "The From address, on the domain `domain_id`.",
                                        "example": "ada@yourdomain.com"
                                    }
                                }
                            },
                            "example": {
                                "name": "Ada from Acme",
                                "email": "ada@yourdomain.com"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            },
            "patch": {
                "operationId": "patchSendersSender",
                "summary": "Update a sender",
                "tags": [
                    "Senders"
                ],
                "x-required-scope": "senders:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "sender",
                        "in": "path",
                        "required": true,
                        "description": "The sender identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "sender"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the sender."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The display name recipients see, e.g. `Acme Support` in `Acme Support <hello@acme.com>`."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "The address this identity sends as. `POST /messages` refuses a `from` that is not a verified sender."
                                                        },
                                                        "domain": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The domain this address sends from, such as `acme.com`. Its DNS details are on `GET /domains/{domain}`."
                                                        },
                                                        "verification": {
                                                            "type": "object",
                                                            "description": "Whether this address may be sent from. Verification checks the domain's public DNS records; there is no token.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "verified",
                                                                        "failed"
                                                                    ],
                                                                    "description": "The one verification answer. Only `verified` permits sending; `pending` and `failed` both do not, and differ in whether a check has run."
                                                                },
                                                                "verified_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the address last passed verification. Set only while `state` is `verified`. Read `state` to know whether the sender works."
                                                                },
                                                                "error": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why the last check failed, usually DNS records still missing. Null when `state` is not `failed`."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this sender was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this sender was last changed."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain_id": {
                                        "type": "string",
                                        "description": "The ID of one of your domains. Copy it from the domain's page in the dashboard, or read it from `GET /domains`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "email_account_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. The mailbox this address belongs to, when it is one of your Mailyte mailboxes. Copy its ID from the mailbox's page, or read it from `GET /email-accounts`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The name recipients see next to the address, as in `Ada from Acme <ada@yourdomain.com>`.",
                                        "example": "Ada from Acme",
                                        "x-example": "Spring newsletter"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "The From address, on the domain `domain_id`.",
                                        "example": "ada@yourdomain.com"
                                    }
                                }
                            },
                            "example": {
                                "name": "Ada from Acme",
                                "email": "ada@yourdomain.com"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteSendersSender",
                "summary": "Delete a sender",
                "tags": [
                    "Senders"
                ],
                "x-required-scope": "senders:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "sender",
                        "in": "path",
                        "required": true,
                        "description": "The sender identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "The sender was deleted. No object is returned: `data` is null. The sender stops appearing in `GET /senders` and reads of it return 404."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/senders/{sender}/verification": {
            "get": {
                "operationId": "getSendersSenderVerification",
                "summary": "Verification a sender",
                "tags": [
                    "Senders"
                ],
                "x-required-scope": "senders:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "sender",
                        "in": "path",
                        "required": true,
                        "description": "The sender identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The live verification check for one sender: what DNS shows now and what is missing.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "sender_verification"
                                                            ]
                                                        },
                                                        "sender_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The sender this check is for."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "pending",
                                                                "verified",
                                                                "failed"
                                                            ],
                                                            "description": "Whether the sender is verified, with the same values as `verification.state` on `GET /senders/{sender}`."
                                                        },
                                                        "error": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Why the last check failed. Null when `state` is not `failed`."
                                                        },
                                                        "checks": {
                                                            "type": "object",
                                                            "description": "The live DNS checks, each true or false.",
                                                            "properties": {
                                                                "spf": {
                                                                    "type": "boolean"
                                                                },
                                                                "dkim": {
                                                                    "type": "boolean"
                                                                },
                                                                "dmarc": {
                                                                    "type": "boolean",
                                                                    "description": "Reported, but never required \u2014 see `requires`."
                                                                }
                                                            }
                                                        },
                                                        "requires": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "spf",
                                                                    "dkim"
                                                                ]
                                                            },
                                                            "description": "Which of `checks` must pass for the sender to verify. DMARC is checked and shown, but does not block."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/senders/{sender}/verify": {
            "post": {
                "operationId": "postSendersSenderVerify",
                "summary": "Verify a sender",
                "tags": [
                    "Senders"
                ],
                "x-required-scope": "senders:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "sender",
                        "in": "path",
                        "required": true,
                        "description": "The sender identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The live verification check for one sender: what DNS shows now and what is missing.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "sender_verification"
                                                            ]
                                                        },
                                                        "sender_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The sender this check is for."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "pending",
                                                                "verified",
                                                                "failed"
                                                            ],
                                                            "description": "Whether the sender is verified, with the same values as `verification.state` on `GET /senders/{sender}`."
                                                        },
                                                        "error": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Why the last check failed. Null when `state` is not `failed`."
                                                        },
                                                        "checks": {
                                                            "type": "object",
                                                            "description": "The live DNS checks, each true or false.",
                                                            "properties": {
                                                                "spf": {
                                                                    "type": "boolean"
                                                                },
                                                                "dkim": {
                                                                    "type": "boolean"
                                                                },
                                                                "dmarc": {
                                                                    "type": "boolean",
                                                                    "description": "Reported, but never required \u2014 see `requires`."
                                                                }
                                                            }
                                                        },
                                                        "requires": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "spf",
                                                                    "dkim"
                                                                ]
                                                            },
                                                            "description": "Which of `checks` must pass for the sender to verify. DMARC is checked and shown, but does not block."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/smtp-credentials": {
            "get": {
                "operationId": "getSmtpCredentials",
                "summary": "List smtp credentials",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "smtp_credential"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "description": "Unique identifier for the credential."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "Your name for the key. It is not used to sign in."
                                                            },
                                                            "username": {
                                                                "type": "string",
                                                                "description": "The SMTP username, to set in your mail library. Delivery events name it. Safe to log."
                                                            },
                                                            "state": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "active",
                                                                    "paused",
                                                                    "revoked",
                                                                    "inactive",
                                                                    "expired",
                                                                    "suspended",
                                                                    "pending_review",
                                                                    "provisioning",
                                                                    "failed",
                                                                    "deleting"
                                                                ],
                                                                "description": "Whether the key can send. Only `active` can.\n\n- `deleting`, `failed`: being removed, or setup failed.\n- `pending_review`: a marketing key waiting for approval.\n- `expired`: past `expires_at`.\n- `suspended`: switched off by us or after delivery failures.\n- `inactive`: retired after a long time unused (the owner was warned three times). Turning it back on keeps the same username and secret.\n- `paused`: on hold because it suddenly sent far more than usual or from a new host. Its mail waits rather than bouncing. The hold lifts by itself (after six hours by default), or now with `POST /smtp-credentials/{credential}/resume`."
                                                            },
                                                            "stream": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "transactional",
                                                                    "marketing"
                                                                ],
                                                                "description": "Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label."
                                                            },
                                                            "domain": {
                                                                "type": "object",
                                                                "description": "The one domain this key may send as.",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "The domain's ID. Always set."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The domain's name. Some responses leave it null; use `domain.id`, or read the key from `GET /smtp-credentials`."
                                                                    }
                                                                }
                                                            },
                                                            "ip_allowlist": {
                                                                "type": "object",
                                                                "description": "Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                                "properties": {
                                                                    "enabled": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "addresses": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                    }
                                                                }
                                                            },
                                                            "limits": {
                                                                "type": "object",
                                                                "description": "Limits for this key alone, below your plan's limits.",
                                                                "properties": {
                                                                    "hourly": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Recipients per hour for this key. Null means no key limit is set; your plan's limit still applies."
                                                                    },
                                                                    "daily": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Recipients per day for this key. Null means no key limit is set; your plan's limit still applies."
                                                                    }
                                                                }
                                                            },
                                                            "tracking_enabled": {
                                                                "type": "boolean",
                                                                "description": "Whether open and click tracking is injected into HTML sent with this credential."
                                                            },
                                                            "last_used_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true,
                                                                "description": "When this key last signed in to send. It can be up to an hour behind. Null means no use has been seen yet, which is not proof the key is idle. For a live figure, use `GET /smtp-credentials/{credential}/usage`."
                                                            },
                                                            "expires_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true,
                                                                "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires (the default). Null does not mean expired."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "description": "ISO 8601 UTC."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postSmtpCredentials",
                "summary": "Create an SMTP credential",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp_credential"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the credential."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the key. It is not used to sign in."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username, to set in your mail library. Delivery events name it. Safe to log."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "paused",
                                                                "revoked",
                                                                "inactive",
                                                                "expired",
                                                                "suspended",
                                                                "pending_review",
                                                                "provisioning",
                                                                "failed",
                                                                "deleting"
                                                            ],
                                                            "description": "Whether the key can send. Only `active` can.\n\n- `deleting`, `failed`: being removed, or setup failed.\n- `pending_review`: a marketing key waiting for approval.\n- `expired`: past `expires_at`.\n- `suspended`: switched off by us or after delivery failures.\n- `inactive`: retired after a long time unused (the owner was warned three times). Turning it back on keeps the same username and secret.\n- `paused`: on hold because it suddenly sent far more than usual or from a new host. Its mail waits rather than bouncing. The hold lifts by itself (after six hours by default), or now with `POST /smtp-credentials/{credential}/resume`."
                                                        },
                                                        "stream": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transactional",
                                                                "marketing"
                                                            ],
                                                            "description": "Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label."
                                                        },
                                                        "domain": {
                                                            "type": "object",
                                                            "description": "The one domain this key may send as.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "description": "The domain's ID. Always set."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The domain's name. Some responses leave it null; use `domain.id`, or read the key from `GET /smtp-credentials`."
                                                                }
                                                            }
                                                        },
                                                        "ip_allowlist": {
                                                            "type": "object",
                                                            "description": "Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "addresses": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "Limits for this key alone, below your plan's limits.",
                                                            "properties": {
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per hour for this key. Null means no key limit is set; your plan's limit still applies."
                                                                },
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per day for this key. Null means no key limit is set; your plan's limit still applies."
                                                                }
                                                            }
                                                        },
                                                        "tracking_enabled": {
                                                            "type": "boolean",
                                                            "description": "Whether open and click tracking is injected into HTML sent with this credential."
                                                        },
                                                        "last_used_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this key last signed in to send. It can be up to an hour behind. Null means no use has been seen yet, which is not proof the key is idle. For a live figure, use `GET /smtp-credentials/{credential}/usage`."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires (the default). Null does not mean expired."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        },
                                                        "password": {
                                                            "type": "string",
                                                            "description": "The SMTP password. **Shown only when the key is created or rotated**, and never again: save it now. If you lose it, rotate the key."
                                                        },
                                                        "smtp": {
                                                            "type": "object",
                                                            "description": "The SMTP host and port to send with, returned only when the key is created. They are the same for every key, so you can save them once.",
                                                            "properties": {
                                                                "host": {
                                                                    "type": "string",
                                                                    "description": "SMTP submission host."
                                                                },
                                                                "port": {
                                                                    "type": "integer",
                                                                    "description": "SMTP submission port."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "A username and password for relaying mail over SMTP, scoped to one domain.\n\n**The password is shown once.** It is stored only as a hash, so nobody \u2014 including\nMailyte \u2014 can read it back. If it is lost, rotate rather than recreate.\n\nUse SMTP when you have an existing application or library that speaks it. Use\n[`POST /messages`](/developer/api/sending/post-messages) when you are writing the\nintegration yourself: it gives you message ids, tags and per-message delivery events\nthat SMTP submission cannot.\n\n**A marketing key needs Bounce protection on.** A key with `stream: \"marketing\"` only\nsends to your contacts whose address has been checked, and Bounce protection is what\nchecks new contacts. Where Bounce protection is available and your account has it\nturned off, creating a marketing key answers `422` with\n`error_code: \"bounce_protection_required\"` and `data.setting_path`, the page where it\nis turned on, and nothing is created. A transactional key is never refused for this.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Website contact form`.",
                                        "example": "Website contact form",
                                        "x-example": "Spring newsletter"
                                    },
                                    "domain_id": {
                                        "type": "string",
                                        "description": "The domain this key sends from. Copy its ID from the domain's page in the dashboard, or read it from `GET /domains`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "allowed_ips": {
                                        "nullable": true,
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 64
                                        },
                                        "description": "The IP addresses allowed to use this key when `ip_allowlist_enabled` is true. Any other address is refused.",
                                        "x-example": [
                                            "203.0.113.10"
                                        ]
                                    },
                                    "ip_allowlist_enabled": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Accept this key only from `allowed_ips`.",
                                        "x-example": true
                                    },
                                    "expires_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Optional. When the key stops working, ISO 8601. Leave it out for a key that does not expire.",
                                        "x-example": "2027-01-01T00:00:00Z"
                                    },
                                    "hourly_limit": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Optional. The most emails this key may send in an hour.",
                                        "x-example": 500
                                    },
                                    "daily_limit": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Optional. The most emails this key may send in a day.",
                                        "x-example": 5000
                                    },
                                    "tracking_enabled": {
                                        "type": "boolean",
                                        "description": "Track opens and clicks in mail sent with this key. Defaults to false for an app (transactional) key, so its links stay on your own domain, and true for a marketing key.",
                                        "x-example": true
                                    },
                                    "stream": {
                                        "enum": [
                                            "transactional",
                                            "marketing"
                                        ],
                                        "type": "string",
                                        "description": "`transactional` for emails your app sends one at a time, like receipts and sign-in codes; `marketing` for newsletters and promotions. They go out from different addresses so one cannot harm the other.",
                                        "x-example": "transactional"
                                    }
                                },
                                "required": [
                                    "name",
                                    "domain_id"
                                ]
                            },
                            "example": {
                                "name": "Website contact form",
                                "domain_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            }
        },
        "/api/v1/smtp-credentials/{credential}": {
            "patch": {
                "operationId": "patchSmtpCredentialsCredential",
                "summary": "Update a smtp credential",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "credential",
                        "in": "path",
                        "required": true,
                        "description": "The credential identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp_credential"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the credential."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the key. It is not used to sign in."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username, to set in your mail library. Delivery events name it. Safe to log."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "paused",
                                                                "revoked",
                                                                "inactive",
                                                                "expired",
                                                                "suspended",
                                                                "pending_review",
                                                                "provisioning",
                                                                "failed",
                                                                "deleting"
                                                            ],
                                                            "description": "Whether the key can send. Only `active` can.\n\n- `deleting`, `failed`: being removed, or setup failed.\n- `pending_review`: a marketing key waiting for approval.\n- `expired`: past `expires_at`.\n- `suspended`: switched off by us or after delivery failures.\n- `inactive`: retired after a long time unused (the owner was warned three times). Turning it back on keeps the same username and secret.\n- `paused`: on hold because it suddenly sent far more than usual or from a new host. Its mail waits rather than bouncing. The hold lifts by itself (after six hours by default), or now with `POST /smtp-credentials/{credential}/resume`."
                                                        },
                                                        "stream": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transactional",
                                                                "marketing"
                                                            ],
                                                            "description": "Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label."
                                                        },
                                                        "domain": {
                                                            "type": "object",
                                                            "description": "The one domain this key may send as.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "description": "The domain's ID. Always set."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The domain's name. Some responses leave it null; use `domain.id`, or read the key from `GET /smtp-credentials`."
                                                                }
                                                            }
                                                        },
                                                        "ip_allowlist": {
                                                            "type": "object",
                                                            "description": "Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "addresses": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "Limits for this key alone, below your plan's limits.",
                                                            "properties": {
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per hour for this key. Null means no key limit is set; your plan's limit still applies."
                                                                },
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per day for this key. Null means no key limit is set; your plan's limit still applies."
                                                                }
                                                            }
                                                        },
                                                        "tracking_enabled": {
                                                            "type": "boolean",
                                                            "description": "Whether open and click tracking is injected into HTML sent with this credential."
                                                        },
                                                        "last_used_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this key last signed in to send. It can be up to an hour behind. Null means no use has been seen yet, which is not proof the key is idle. For a live figure, use `GET /smtp-credentials/{credential}/usage`."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires (the default). Null does not mean expired."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Change a credential's name, expiry, per-key limits, tracking or stream. Send only the\nfields you are changing.\n\n**Changing a key to `stream: \"marketing\"` needs Bounce protection on**, for the same\nreason as creating one: a marketing key only sends to your checked contacts. Where\nBounce protection is available and your account has it turned off, the change answers\n`422` with `error_code: \"bounce_protection_required\"` and `data.setting_path`, and the\nkey is left as it was. A key that is already on the marketing stream is never refused\nfor this.\n\n**While your marketing is paused, changing a marketing key to transactional can be\nrefused.** The change then answers `409` with `error_code: \"marketing_paused\"`, and\nthe key is left as it was. Try again when your marketing can send again.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Its name, shown in the dashboard.",
                                        "x-example": "Spring newsletter"
                                    },
                                    "expires_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Optional. When the key stops working, ISO 8601. Leave it out for a key that does not expire.",
                                        "x-example": "2027-01-01T00:00:00Z"
                                    },
                                    "hourly_limit": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Optional. The most emails this key may send in an hour.",
                                        "x-example": 500
                                    },
                                    "daily_limit": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Optional. The most emails this key may send in a day.",
                                        "x-example": 5000
                                    },
                                    "tracking_enabled": {
                                        "type": "boolean",
                                        "description": "Track opens and clicks in mail sent with this key. Defaults to false for an app (transactional) key, so its links stay on your own domain, and true for a marketing key.",
                                        "x-example": true
                                    },
                                    "stream": {
                                        "enum": [
                                            "transactional",
                                            "marketing"
                                        ],
                                        "type": "string",
                                        "description": "`transactional` for emails your app sends one at a time, like receipts and sign-in codes; `marketing` for newsletters and promotions. They go out from different addresses so one cannot harm the other.",
                                        "x-example": "transactional"
                                    }
                                }
                            },
                            "example": {
                                "name": "Spring newsletter",
                                "expires_at": "2027-01-01T00:00:00Z"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteSmtpCredentialsCredential",
                "summary": "Delete a smtp credential",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "credential",
                        "in": "path",
                        "required": true,
                        "description": "The credential identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No body. The credential is scheduled for teardown on the mail server and stops authenticating; until the deprovision completes it is still listed with `state: \"deleting\"`."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/smtp-credentials/{credential}/rotate": {
            "post": {
                "operationId": "postSmtpCredentialsCredentialRotate",
                "summary": "Rotate a smtp credential",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "credential",
                        "in": "path",
                        "required": true,
                        "description": "The credential identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp_credential"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the credential."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the key. It is not used to sign in."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username, to set in your mail library. Delivery events name it. Safe to log."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "paused",
                                                                "revoked",
                                                                "inactive",
                                                                "expired",
                                                                "suspended",
                                                                "pending_review",
                                                                "provisioning",
                                                                "failed",
                                                                "deleting"
                                                            ],
                                                            "description": "Whether the key can send. Only `active` can.\n\n- `deleting`, `failed`: being removed, or setup failed.\n- `pending_review`: a marketing key waiting for approval.\n- `expired`: past `expires_at`.\n- `suspended`: switched off by us or after delivery failures.\n- `inactive`: retired after a long time unused (the owner was warned three times). Turning it back on keeps the same username and secret.\n- `paused`: on hold because it suddenly sent far more than usual or from a new host. Its mail waits rather than bouncing. The hold lifts by itself (after six hours by default), or now with `POST /smtp-credentials/{credential}/resume`."
                                                        },
                                                        "stream": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transactional",
                                                                "marketing"
                                                            ],
                                                            "description": "Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label."
                                                        },
                                                        "domain": {
                                                            "type": "object",
                                                            "description": "The one domain this key may send as.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "description": "The domain's ID. Always set."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The domain's name. Some responses leave it null; use `domain.id`, or read the key from `GET /smtp-credentials`."
                                                                }
                                                            }
                                                        },
                                                        "ip_allowlist": {
                                                            "type": "object",
                                                            "description": "Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "addresses": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "Limits for this key alone, below your plan's limits.",
                                                            "properties": {
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per hour for this key. Null means no key limit is set; your plan's limit still applies."
                                                                },
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per day for this key. Null means no key limit is set; your plan's limit still applies."
                                                                }
                                                            }
                                                        },
                                                        "tracking_enabled": {
                                                            "type": "boolean",
                                                            "description": "Whether open and click tracking is injected into HTML sent with this credential."
                                                        },
                                                        "last_used_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this key last signed in to send. It can be up to an hour behind. Null means no use has been seen yet, which is not proof the key is idle. For a live figure, use `GET /smtp-credentials/{credential}/usage`."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires (the default). Null does not mean expired."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        },
                                                        "password": {
                                                            "type": "string",
                                                            "description": "The SMTP password. **Shown only when the key is created or rotated**, and never again: save it now. If you lose it, rotate the key."
                                                        },
                                                        "smtp": {
                                                            "type": "object",
                                                            "description": "The SMTP host and port to send with, returned only when the key is created. They are the same for every key, so you can save them once.",
                                                            "properties": {
                                                                "host": {
                                                                    "type": "string",
                                                                    "description": "SMTP submission host."
                                                                },
                                                                "port": {
                                                                    "type": "integer",
                                                                    "description": "SMTP submission port."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/smtp-credentials/{credential}/revoke": {
            "post": {
                "operationId": "postSmtpCredentialsCredentialRevoke",
                "summary": "Revoke a smtp credential",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "credential",
                        "in": "path",
                        "required": true,
                        "description": "The credential identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp_credential"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the credential."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the key. It is not used to sign in."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username, to set in your mail library. Delivery events name it. Safe to log."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "paused",
                                                                "revoked",
                                                                "inactive",
                                                                "expired",
                                                                "suspended",
                                                                "pending_review",
                                                                "provisioning",
                                                                "failed",
                                                                "deleting"
                                                            ],
                                                            "description": "Whether the key can send. Only `active` can.\n\n- `deleting`, `failed`: being removed, or setup failed.\n- `pending_review`: a marketing key waiting for approval.\n- `expired`: past `expires_at`.\n- `suspended`: switched off by us or after delivery failures.\n- `inactive`: retired after a long time unused (the owner was warned three times). Turning it back on keeps the same username and secret.\n- `paused`: on hold because it suddenly sent far more than usual or from a new host. Its mail waits rather than bouncing. The hold lifts by itself (after six hours by default), or now with `POST /smtp-credentials/{credential}/resume`."
                                                        },
                                                        "stream": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transactional",
                                                                "marketing"
                                                            ],
                                                            "description": "Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label."
                                                        },
                                                        "domain": {
                                                            "type": "object",
                                                            "description": "The one domain this key may send as.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "description": "The domain's ID. Always set."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The domain's name. Some responses leave it null; use `domain.id`, or read the key from `GET /smtp-credentials`."
                                                                }
                                                            }
                                                        },
                                                        "ip_allowlist": {
                                                            "type": "object",
                                                            "description": "Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "addresses": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "Limits for this key alone, below your plan's limits.",
                                                            "properties": {
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per hour for this key. Null means no key limit is set; your plan's limit still applies."
                                                                },
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per day for this key. Null means no key limit is set; your plan's limit still applies."
                                                                }
                                                            }
                                                        },
                                                        "tracking_enabled": {
                                                            "type": "boolean",
                                                            "description": "Whether open and click tracking is injected into HTML sent with this credential."
                                                        },
                                                        "last_used_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this key last signed in to send. It can be up to an hour behind. Null means no use has been seen yet, which is not proof the key is idle. For a live figure, use `GET /smtp-credentials/{credential}/usage`."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires (the default). Null does not mean expired."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/smtp-credentials/{credential}/enable": {
            "post": {
                "operationId": "postSmtpCredentialsCredentialEnable",
                "summary": "Enable a smtp credential",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "credential",
                        "in": "path",
                        "required": true,
                        "description": "The credential identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp_credential"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the credential."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the key. It is not used to sign in."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username, to set in your mail library. Delivery events name it. Safe to log."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "paused",
                                                                "revoked",
                                                                "inactive",
                                                                "expired",
                                                                "suspended",
                                                                "pending_review",
                                                                "provisioning",
                                                                "failed",
                                                                "deleting"
                                                            ],
                                                            "description": "Whether the key can send. Only `active` can.\n\n- `deleting`, `failed`: being removed, or setup failed.\n- `pending_review`: a marketing key waiting for approval.\n- `expired`: past `expires_at`.\n- `suspended`: switched off by us or after delivery failures.\n- `inactive`: retired after a long time unused (the owner was warned three times). Turning it back on keeps the same username and secret.\n- `paused`: on hold because it suddenly sent far more than usual or from a new host. Its mail waits rather than bouncing. The hold lifts by itself (after six hours by default), or now with `POST /smtp-credentials/{credential}/resume`."
                                                        },
                                                        "stream": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transactional",
                                                                "marketing"
                                                            ],
                                                            "description": "Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label."
                                                        },
                                                        "domain": {
                                                            "type": "object",
                                                            "description": "The one domain this key may send as.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "description": "The domain's ID. Always set."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The domain's name. Some responses leave it null; use `domain.id`, or read the key from `GET /smtp-credentials`."
                                                                }
                                                            }
                                                        },
                                                        "ip_allowlist": {
                                                            "type": "object",
                                                            "description": "Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "addresses": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "Limits for this key alone, below your plan's limits.",
                                                            "properties": {
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per hour for this key. Null means no key limit is set; your plan's limit still applies."
                                                                },
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per day for this key. Null means no key limit is set; your plan's limit still applies."
                                                                }
                                                            }
                                                        },
                                                        "tracking_enabled": {
                                                            "type": "boolean",
                                                            "description": "Whether open and click tracking is injected into HTML sent with this credential."
                                                        },
                                                        "last_used_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this key last signed in to send. It can be up to an hour behind. Null means no use has been seen yet, which is not proof the key is idle. For a live figure, use `GET /smtp-credentials/{credential}/usage`."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires (the default). Null does not mean expired."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/smtp-credentials/{credential}/resume": {
            "post": {
                "operationId": "postSmtpCredentialsCredentialResume",
                "summary": "Resume a paused SMTP credential",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "credential",
                        "in": "path",
                        "required": true,
                        "description": "The credential identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp_credential"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the credential."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the key. It is not used to sign in."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username, to set in your mail library. Delivery events name it. Safe to log."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "paused",
                                                                "revoked",
                                                                "inactive",
                                                                "expired",
                                                                "suspended",
                                                                "pending_review",
                                                                "provisioning",
                                                                "failed",
                                                                "deleting"
                                                            ],
                                                            "description": "Whether the key can send. Only `active` can.\n\n- `deleting`, `failed`: being removed, or setup failed.\n- `pending_review`: a marketing key waiting for approval.\n- `expired`: past `expires_at`.\n- `suspended`: switched off by us or after delivery failures.\n- `inactive`: retired after a long time unused (the owner was warned three times). Turning it back on keeps the same username and secret.\n- `paused`: on hold because it suddenly sent far more than usual or from a new host. Its mail waits rather than bouncing. The hold lifts by itself (after six hours by default), or now with `POST /smtp-credentials/{credential}/resume`."
                                                        },
                                                        "stream": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transactional",
                                                                "marketing"
                                                            ],
                                                            "description": "Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label."
                                                        },
                                                        "domain": {
                                                            "type": "object",
                                                            "description": "The one domain this key may send as.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "description": "The domain's ID. Always set."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The domain's name. Some responses leave it null; use `domain.id`, or read the key from `GET /smtp-credentials`."
                                                                }
                                                            }
                                                        },
                                                        "ip_allowlist": {
                                                            "type": "object",
                                                            "description": "Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "addresses": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "Limits for this key alone, below your plan's limits.",
                                                            "properties": {
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per hour for this key. Null means no key limit is set; your plan's limit still applies."
                                                                },
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per day for this key. Null means no key limit is set; your plan's limit still applies."
                                                                }
                                                            }
                                                        },
                                                        "tracking_enabled": {
                                                            "type": "boolean",
                                                            "description": "Whether open and click tracking is injected into HTML sent with this credential."
                                                        },
                                                        "last_used_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this key last signed in to send. It can be up to an hour behind. Null means no use has been seen yet, which is not proof the key is idle. For a live figure, use `GET /smtp-credentials/{credential}/usage`."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires (the default). Null does not mean expired."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Lifts a pause the mail server placed on the credential after it sent unlike itself \u2014\nfar more recipients or domains in an hour than its own history, or from a sending host\nit had never used \u2014 and lets the mail it was holding go.\n\nA pause is not a revocation. The credential still authenticates and nothing was\nbounced: mail submitted during the pause was deferred, and delivers once the pause\nlifts. It also lifts on its own after the pause window (six hours by default) if nobody\nacts. The credential reads `state: \"paused\"` while it is held.\n\nUse this when the activity was yours. If it was not, `revoke` the credential instead\nand create a new one \u2014 resuming a stolen key resumes the theft. Calling this on a\ncredential that is not paused is harmless and returns it unchanged.\n\nA transactional credential paused because it kept sending newsletters cannot be resumed\nhere: it answers `409` with `error_code: \"newsletter_hold\"`, and only Mailyte support\nstarts it again. Newsletters and other bulk email go through a marketing credential.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/smtp-credentials/{credential}/ip-allowlist": {
            "put": {
                "operationId": "putSmtpCredentialsCredentialIpAllowlist",
                "summary": "Replace an SMTP credential's IP allowlist",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "credential",
                        "in": "path",
                        "required": true,
                        "description": "The credential identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp_credential"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the credential."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the key. It is not used to sign in."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username, to set in your mail library. Delivery events name it. Safe to log."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "paused",
                                                                "revoked",
                                                                "inactive",
                                                                "expired",
                                                                "suspended",
                                                                "pending_review",
                                                                "provisioning",
                                                                "failed",
                                                                "deleting"
                                                            ],
                                                            "description": "Whether the key can send. Only `active` can.\n\n- `deleting`, `failed`: being removed, or setup failed.\n- `pending_review`: a marketing key waiting for approval.\n- `expired`: past `expires_at`.\n- `suspended`: switched off by us or after delivery failures.\n- `inactive`: retired after a long time unused (the owner was warned three times). Turning it back on keeps the same username and secret.\n- `paused`: on hold because it suddenly sent far more than usual or from a new host. Its mail waits rather than bouncing. The hold lifts by itself (after six hours by default), or now with `POST /smtp-credentials/{credential}/resume`."
                                                        },
                                                        "stream": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transactional",
                                                                "marketing"
                                                            ],
                                                            "description": "Which lane mail sent with this credential is treated as. The stream decides reputation handling and marketing gating; it is not a label."
                                                        },
                                                        "domain": {
                                                            "type": "object",
                                                            "description": "The one domain this key may send as.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "description": "The domain's ID. Always set."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The domain's name. Some responses leave it null; use `domain.id`, or read the key from `GET /smtp-credentials`."
                                                                }
                                                            }
                                                        },
                                                        "ip_allowlist": {
                                                            "type": "object",
                                                            "description": "Enforced by the mail server at AUTH time, not by this API. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                            "properties": {
                                                                "enabled": {
                                                                    "type": "boolean"
                                                                },
                                                                "addresses": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "Limits for this key alone, below your plan's limits.",
                                                            "properties": {
                                                                "hourly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per hour for this key. Null means no key limit is set; your plan's limit still applies."
                                                                },
                                                                "daily": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients per day for this key. Null means no key limit is set; your plan's limit still applies."
                                                                }
                                                            }
                                                        },
                                                        "tracking_enabled": {
                                                            "type": "boolean",
                                                            "description": "Whether open and click tracking is injected into HTML sent with this credential."
                                                        },
                                                        "last_used_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When this key last signed in to send. It can be up to an hour behind. Null means no use has been seen yet, which is not proof the key is idle. For a live figure, use `GET /smtp-credentials/{credential}/usage`."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires (the default). Null does not mean expired."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "allowed_ips": [
                                        "203.0.113.10",
                                        "203.0.113.11"
                                    ],
                                    "ip_allowlist_enabled": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "The list REPLACES whatever is there \u2014 send the full set, not an addition. Enabling an allowlist that does not contain your sending host stops that host relaying immediately.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "allowed_ips": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 64
                                        },
                                        "description": "The IP addresses allowed to use this key when `ip_allowlist_enabled` is true. Any other address is refused.",
                                        "x-example": [
                                            "203.0.113.10"
                                        ]
                                    },
                                    "ip_allowlist_enabled": {
                                        "type": "boolean",
                                        "description": "Accept this key only from `allowed_ips`.",
                                        "x-example": true
                                    }
                                },
                                "required": [
                                    "allowed_ips",
                                    "ip_allowlist_enabled"
                                ]
                            },
                            "example": {
                                "allowed_ips": [
                                    "203.0.113.10",
                                    "203.0.113.11"
                                ],
                                "ip_allowlist_enabled": true
                            }
                        }
                    }
                },
                "x-body-source": "service-rules"
            }
        },
        "/api/v1/smtp-credentials/{credential}/usage": {
            "get": {
                "operationId": "getSmtpCredentialsCredentialUsage",
                "summary": "Usage a smtp credential",
                "tags": [
                    "SMTP credentials"
                ],
                "x-required-scope": "smtp:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "credential",
                        "in": "path",
                        "required": true,
                        "description": "The credential identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp_credential_usage"
                                                            ]
                                                        },
                                                        "window": {
                                                            "type": "object",
                                                            "description": "The period these counts cover, stated in full so you do not have to infer the end from the start.",
                                                            "properties": {
                                                                "days": {
                                                                    "type": "integer",
                                                                    "description": "Length of the window in days."
                                                                },
                                                                "since": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the counting window starts, in ISO 8601 UTC. Null when `counted` is false."
                                                                },
                                                                "until": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "description": "ISO 8601 UTC. The moment the counts were computed against."
                                                                }
                                                            }
                                                        },
                                                        "counted": {
                                                            "type": "boolean",
                                                            "description": "Whether the counts below were measured. False when the key is not set up on the mail server yet; the counts are then null, not 0."
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Messages sent with this key. Null means unknown, not 0."
                                                        },
                                                        "delivered": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Messages accepted by the receiving server. Null means unknown, not 0."
                                                        },
                                                        "bounced": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Messages permanently refused. Null means unknown, not 0."
                                                        },
                                                        "deferred": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Messages temporarily refused and retried. Null means unknown, not 0."
                                                        },
                                                        "rejected": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Messages we refused before sending. Null means unknown, not 0."
                                                        },
                                                        "last_used_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the key last signed in to send, in ISO 8601 UTC, read live from the mail server. Null means it has never been used."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/email-logs": {
            "get": {
                "operationId": "getEmailLogs",
                "summary": "List delivery events",
                "tags": [
                    "Events"
                ],
                "x-required-scope": "events:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "event"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "This event's ID, the value `GET /email-logs/{event}` takes."
                                                                    },
                                                                    "type": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "email.submitted",
                                                                            "email.accepted",
                                                                            "email.delivered",
                                                                            "email.deferred",
                                                                            "email.bounced",
                                                                            "email.dropped",
                                                                            "email.rejected",
                                                                            "email.inbound",
                                                                            "tracking.open",
                                                                            "tracking.click",
                                                                            "tracking.unsubscribe",
                                                                            "delivery.complaint",
                                                                            "spam.reported",
                                                                            "storage.quota.warning",
                                                                            "storage.quota.exceeded",
                                                                            "quota.warning"
                                                                        ],
                                                                        "description": "What happened, exactly as `?event_type=` accepts it. `email.submitted` is written when we accept a message. A complaint is `delivery.complaint`. `quota.warning` is an older name for `storage.quota.warning`. The `storage.*` and `spam.reported` events are about a mailbox rather than one of your messages."
                                                                    },
                                                                    "recipient": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The address the event is about. Rarely null, when the mail server's report gave no address."
                                                                    },
                                                                    "detail": {
                                                                        "type": "object",
                                                                        "description": "The extras that only some event types carry. Grouped rather than flat: on a plain delivery all four are null, and flat they read as four missing fields instead of one absent category.",
                                                                        "properties": {
                                                                            "ip_address": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Who opened or clicked. Null on everything else."
                                                                            },
                                                                            "user_agent": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The app that opened or clicked, as it named itself. Often null, for example when an image proxy loaded the message."
                                                                            },
                                                                            "url": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The link that was clicked. Set only when `type` is `tracking.click`."
                                                                            },
                                                                            "reason": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Why a message bounced, was deferred or was dropped, in the receiving server's words. Null when nothing went wrong."
                                                                            },
                                                                            "not_sent_reason": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "does_not_exist",
                                                                                    "dead_domain",
                                                                                    "misspelt_domain",
                                                                                    "suppressed",
                                                                                    "disposable",
                                                                                    "not_a_contact",
                                                                                    "not_checked",
                                                                                    "inbox_full",
                                                                                    null
                                                                                ],
                                                                                "description": "Set when Mailyte stopped the message before it left, so it was never sent and is not a bounce:\n\n- `does_not_exist`: the address is known not to exist.\n- `dead_domain`: the domain takes no mail.\n- `misspelt_domain`: the domain is misspelled, such as gmail.con.\n- `suppressed`: the address is on your suppression list.\n- `disposable`: a throwaway address.\n- `not_a_contact` or `not_checked`: a marketing key sends only to checked contacts.\n- `inbox_full`: the inbox is full.\n\nRemove or correct the address in your app. Null for everything else."
                                                                            }
                                                                        }
                                                                    },
                                                                    "message": {
                                                                        "type": "object",
                                                                        "description": "The message this event is about, without its body. `subject`, `from` and `tags` are set only on the `email.submitted` row; `GET /email-logs/{event}` returns them for any event.",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Mailyte's ID for the message: a ULID, without angle brackets. Use it with `GET /email-logs/messages/{id}`. It is not the Message-ID."
                                                                            },
                                                                            "message_id": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The Message-ID header, angle brackets included, such as `<01JBT8XQ2M\u2026@example.com>`. It is in the recipient's headers and in any bounce. Use it, percent-encoded, with `GET /domains/{domain}/messages/{messageId}`. Null for an `email.dropped` event, because the message was never sent."
                                                                            },
                                                                            "subject": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The subject. In this list it is set only on the `email.submitted` row; `GET /email-logs/{event}` returns it for any event."
                                                                            },
                                                                            "from": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "email": {
                                                                                        "type": "string",
                                                                                        "nullable": true,
                                                                                        "description": "The sending address. In this list it is set only on the `email.submitted` row, as with `subject`."
                                                                                    },
                                                                                    "name": {
                                                                                        "type": "string",
                                                                                        "nullable": true,
                                                                                        "description": "The sender's display name. Null when there is none, or on a list row that is not `email.submitted`."
                                                                                    }
                                                                                }
                                                                            },
                                                                            "tags": {
                                                                                "type": "array",
                                                                                "nullable": true,
                                                                                "items": {
                                                                                    "type": "string"
                                                                                },
                                                                                "description": "Your labels from the send. `[]` means the message had no tags. Null means this row is not `email.submitted`, so the tags are not shown here."
                                                                            },
                                                                            "metadata": {
                                                                                "type": "object",
                                                                                "nullable": true,
                                                                                "additionalProperties": {
                                                                                    "type": "string"
                                                                                },
                                                                                "description": "The metadata you set when sending, returned unchanged on every event for this message. `{}` means there was none. Null means this row is not `email.submitted`."
                                                                            }
                                                                        }
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When we recorded the event, which can be a little after it happened."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Every event recorded for your organization's mail: accepted, delivered, deferred,\nbounced, complained, opened, clicked, dropped.\n\nPolling this is the simple way to follow a send. Receiving\n[webhooks](/developer/webhooks) is the better one \u2014 it costs you no requests and tells\nyou sooner.\n\n**Opens and clicks are not reliable, by nature.** Open tracking depends on a remote\nimage loading, which privacy proxies fetch on the recipient's behalf and many clients\nblock entirely. Treat them as a weak signal about a population, never as proof about a\nperson."
            }
        },
        "/api/v1/email-logs/messages": {
            "get": {
                "operationId": "getEmailLogsMessages",
                "summary": "Messages (email log)",
                "tags": [
                    "Events"
                ],
                "x-required-scope": "events:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "message"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Mailyte's ID for the message, the value `GET /email-logs/messages/{id}` takes. It is not the Message-ID."
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The Message-ID header, angle brackets included, for `GET /domains/{domain}/messages/{messageId}`. Null when the message never had one."
                                                                    },
                                                                    "subject": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The subject. Null when none of this message's events has one."
                                                                    },
                                                                    "from": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "email": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The sending address. Null when none of this message's events names one."
                                                                            },
                                                                            "name": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The sender's display name. Null when there is none."
                                                                            }
                                                                        }
                                                                    },
                                                                    "recipient": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The one address this copy was sent to. A message to several people appears as one row per recipient."
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "submitted",
                                                                            "sent",
                                                                            "delivered",
                                                                            "deferred",
                                                                            "bounced",
                                                                            "rejected",
                                                                            "dropped",
                                                                            "opened",
                                                                            "clicked",
                                                                            "complained",
                                                                            "unsubscribed",
                                                                            "unknown"
                                                                        ],
                                                                        "description": "The message's latest outcome. A value we do not recognise is shown as `unknown`. `sent` and `complained` do not occur today."
                                                                    },
                                                                    "not_sent_reason": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "does_not_exist",
                                                                            "dead_domain",
                                                                            "misspelt_domain",
                                                                            "suppressed",
                                                                            "disposable",
                                                                            "not_a_contact",
                                                                            "not_checked",
                                                                            "inbox_full",
                                                                            null
                                                                        ],
                                                                        "description": "Set when Mailyte stopped the message before it left, so it was never sent and is not a bounce:\n\n- `does_not_exist`: the address is known not to exist.\n- `dead_domain`: the domain takes no mail.\n- `misspelt_domain`: the domain is misspelled, such as gmail.con.\n- `suppressed`: the address is on your suppression list.\n- `disposable`: a throwaway address.\n- `not_a_contact` or `not_checked`: a marketing key sends only to checked contacts.\n- `inbox_full`: the inbox is full.\n\nRemove or correct the address in your app. Null for everything else."
                                                                    },
                                                                    "activity": {
                                                                        "type": "object",
                                                                        "description": "Counts over every event recorded for this message.",
                                                                        "properties": {
                                                                            "total": {
                                                                                "type": "integer",
                                                                                "description": "All events, of any type."
                                                                            },
                                                                            "opens": {
                                                                                "type": "integer",
                                                                                "description": "Every open, not unique people: one person opening twice counts twice."
                                                                            },
                                                                            "clicks": {
                                                                                "type": "integer",
                                                                                "description": "Every `tracking.click`, not unique links."
                                                                            },
                                                                            "types": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                },
                                                                                "description": "The distinct `type` values seen for this message, from the same set as an event's `type`."
                                                                            }
                                                                        }
                                                                    },
                                                                    "first_event_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the first event happened, in ISO 8601 UTC."
                                                                    },
                                                                    "last_event_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the latest event happened, in ISO 8601 UTC. `status` comes from this event."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/email-logs/messages/{messageKey}": {
            "get": {
                "operationId": "getEmailLogsMessagesMessageKey",
                "summary": "Get a message timeline",
                "tags": [
                    "Events"
                ],
                "x-required-scope": "events:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "messageKey",
                        "in": "path",
                        "required": true,
                        "description": "The message key identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "message"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Mailyte's ID for the message: a ULID, without angle brackets. Use it with `GET /email-logs/messages/{id}`. It is not the Message-ID."
                                                        },
                                                        "message_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Message-ID header, angle brackets included, such as `<01JBT8XQ2M\u2026@example.com>`. It is in the recipient's headers and in any bounce. Use it, percent-encoded, with `GET /domains/{domain}/messages/{messageId}`. Null for an `email.dropped` event, because the message was never sent."
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The subject. In this list it is set only on the `email.submitted` row; `GET /email-logs/{event}` returns it for any event."
                                                        },
                                                        "from": {
                                                            "type": "object",
                                                            "properties": {
                                                                "email": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sending address. In this list it is set only on the `email.submitted` row, as with `subject`."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name. Null when there is none, or on a list row that is not `email.submitted`."
                                                                }
                                                            }
                                                        },
                                                        "tags": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "Your labels from the send. `[]` means the message had no tags. Null means this row is not `email.submitted`, so the tags are not shown here."
                                                        },
                                                        "metadata": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": {
                                                                "type": "string"
                                                            },
                                                            "description": "The metadata you set when sending, returned unchanged on every event for this message. `{}` means there was none. Null means this row is not `email.submitted`."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The HTML body as sent. Null when the message was text only, or we never saw it being sent."
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The plain-text body as sent. Null when there was none, or we never saw it being sent."
                                                        },
                                                        "recipient": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The one address this copy was sent to. A message to several people appears as one message per recipient."
                                                        },
                                                        "events": {
                                                            "type": "array",
                                                            "description": "Everything that happened to this message, oldest first, in the same shape as `GET /email-logs`.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "event"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "This event's ID, the value `GET /email-logs/{event}` takes."
                                                                    },
                                                                    "type": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "email.submitted",
                                                                            "email.accepted",
                                                                            "email.delivered",
                                                                            "email.deferred",
                                                                            "email.bounced",
                                                                            "email.dropped",
                                                                            "email.rejected",
                                                                            "email.inbound",
                                                                            "tracking.open",
                                                                            "tracking.click",
                                                                            "tracking.unsubscribe",
                                                                            "delivery.complaint",
                                                                            "spam.reported",
                                                                            "storage.quota.warning",
                                                                            "storage.quota.exceeded",
                                                                            "quota.warning"
                                                                        ],
                                                                        "description": "What happened, exactly as `?event_type=` accepts it. `email.submitted` is written when we accept a message. A complaint is `delivery.complaint`. `quota.warning` is an older name for `storage.quota.warning`. The `storage.*` and `spam.reported` events are about a mailbox rather than one of your messages."
                                                                    },
                                                                    "recipient": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The address the event is about. Rarely null, when the mail server's report gave no address."
                                                                    },
                                                                    "detail": {
                                                                        "type": "object",
                                                                        "description": "The extras that only some event types carry. Grouped rather than flat: on a plain delivery all four are null, and flat they read as four missing fields instead of one absent category.",
                                                                        "properties": {
                                                                            "ip_address": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Who opened or clicked. Null on everything else."
                                                                            },
                                                                            "user_agent": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The app that opened or clicked, as it named itself. Often null, for example when an image proxy loaded the message."
                                                                            },
                                                                            "url": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The link that was clicked. Set only when `type` is `tracking.click`."
                                                                            },
                                                                            "reason": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Why a message bounced, was deferred or was dropped, in the receiving server's words. Null when nothing went wrong."
                                                                            },
                                                                            "not_sent_reason": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "does_not_exist",
                                                                                    "dead_domain",
                                                                                    "misspelt_domain",
                                                                                    "suppressed",
                                                                                    "disposable",
                                                                                    "not_a_contact",
                                                                                    "not_checked",
                                                                                    "inbox_full",
                                                                                    null
                                                                                ],
                                                                                "description": "Set when Mailyte stopped the message before it left, so it was never sent and is not a bounce:\n\n- `does_not_exist`: the address is known not to exist.\n- `dead_domain`: the domain takes no mail.\n- `misspelt_domain`: the domain is misspelled, such as gmail.con.\n- `suppressed`: the address is on your suppression list.\n- `disposable`: a throwaway address.\n- `not_a_contact` or `not_checked`: a marketing key sends only to checked contacts.\n- `inbox_full`: the inbox is full.\n\nRemove or correct the address in your app. Null for everything else."
                                                                            }
                                                                        }
                                                                    },
                                                                    "message": {
                                                                        "type": "object",
                                                                        "description": "The message this event is about, without its body. `subject`, `from` and `tags` are set only on the `email.submitted` row; `GET /email-logs/{event}` returns them for any event.",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Mailyte's ID for the message: a ULID, without angle brackets. Use it with `GET /email-logs/messages/{id}`. It is not the Message-ID."
                                                                            },
                                                                            "message_id": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The Message-ID header, angle brackets included, such as `<01JBT8XQ2M\u2026@example.com>`. It is in the recipient's headers and in any bounce. Use it, percent-encoded, with `GET /domains/{domain}/messages/{messageId}`. Null for an `email.dropped` event, because the message was never sent."
                                                                            },
                                                                            "subject": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The subject. In this list it is set only on the `email.submitted` row; `GET /email-logs/{event}` returns it for any event."
                                                                            },
                                                                            "from": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "email": {
                                                                                        "type": "string",
                                                                                        "nullable": true,
                                                                                        "description": "The sending address. In this list it is set only on the `email.submitted` row, as with `subject`."
                                                                                    },
                                                                                    "name": {
                                                                                        "type": "string",
                                                                                        "nullable": true,
                                                                                        "description": "The sender's display name. Null when there is none, or on a list row that is not `email.submitted`."
                                                                                    }
                                                                                }
                                                                            },
                                                                            "tags": {
                                                                                "type": "array",
                                                                                "nullable": true,
                                                                                "items": {
                                                                                    "type": "string"
                                                                                },
                                                                                "description": "Your labels from the send. `[]` means the message had no tags. Null means this row is not `email.submitted`, so the tags are not shown here."
                                                                            },
                                                                            "metadata": {
                                                                                "type": "object",
                                                                                "nullable": true,
                                                                                "additionalProperties": {
                                                                                    "type": "string"
                                                                                },
                                                                                "description": "The metadata you set when sending, returned unchanged on every event for this message. `{}` means there was none. Null means this row is not `email.submitted`."
                                                                            }
                                                                        }
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When we recorded the event, which can be a little after it happened."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Every event for one message, oldest first \u2014 the whole story of a single send in one call."
            }
        },
        "/api/v1/email-logs/{event}": {
            "get": {
                "operationId": "getEmailLogsEvent",
                "summary": "Retrieve a email log",
                "tags": [
                    "Events"
                ],
                "x-required-scope": "events:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "event",
                        "in": "path",
                        "required": true,
                        "description": "The event identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "event"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "This event."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "email.submitted",
                                                                "email.accepted",
                                                                "email.delivered",
                                                                "email.deferred",
                                                                "email.bounced",
                                                                "email.dropped",
                                                                "email.rejected",
                                                                "email.inbound",
                                                                "tracking.open",
                                                                "tracking.click",
                                                                "tracking.unsubscribe",
                                                                "delivery.complaint",
                                                                "spam.reported",
                                                                "storage.quota.warning",
                                                                "storage.quota.exceeded",
                                                                "quota.warning"
                                                            ],
                                                            "description": "What happened, exactly as `?event_type=` accepts it. `email.submitted` is written when we accept a message. A complaint is `delivery.complaint`. `quota.warning` is an older name for `storage.quota.warning`. The `storage.*` and `spam.reported` events are about a mailbox rather than one of your messages."
                                                        },
                                                        "recipient": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The address the event is about. Rarely null, when the mail server's report gave no address."
                                                        },
                                                        "detail": {
                                                            "type": "object",
                                                            "description": "The extras that only some event types carry. Grouped rather than flat: on a plain delivery all four are null, and flat they read as four missing fields instead of one absent category.",
                                                            "properties": {
                                                                "ip_address": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Who opened or clicked. Null on everything else."
                                                                },
                                                                "user_agent": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The app that opened or clicked, as it named itself. Often null, for example when an image proxy loaded the message."
                                                                },
                                                                "url": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The link that was clicked. Set only when `type` is `tracking.click`."
                                                                },
                                                                "reason": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why a message bounced, was deferred or was dropped, in the receiving server's words. Null when nothing went wrong."
                                                                },
                                                                "not_sent_reason": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "does_not_exist",
                                                                        "dead_domain",
                                                                        "misspelt_domain",
                                                                        "suppressed",
                                                                        "disposable",
                                                                        "not_a_contact",
                                                                        "not_checked",
                                                                        "inbox_full",
                                                                        null
                                                                    ],
                                                                    "description": "Set when Mailyte stopped the message before it left, so it was never sent and is not a bounce:\n\n- `does_not_exist`: the address is known not to exist.\n- `dead_domain`: the domain takes no mail.\n- `misspelt_domain`: the domain is misspelled, such as gmail.con.\n- `suppressed`: the address is on your suppression list.\n- `disposable`: a throwaway address.\n- `not_a_contact` or `not_checked`: a marketing key sends only to checked contacts.\n- `inbox_full`: the inbox is full.\n\nRemove or correct the address in your app. Null for everything else."
                                                                }
                                                            }
                                                        },
                                                        "message": {
                                                            "type": "object",
                                                            "description": "The message this event is about, with its body as sent. `message.id` leads to the full timeline.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Mailyte's ID for the message: a ULID, without angle brackets. Use it with `GET /email-logs/messages/{id}`. It is not the Message-ID."
                                                                },
                                                                "message_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The Message-ID header, angle brackets included, such as `<01JBT8XQ2M\u2026@example.com>`. It is in the recipient's headers and in any bounce. Use it, percent-encoded, with `GET /domains/{domain}/messages/{messageId}`. Null for an `email.dropped` event, because the message was never sent."
                                                                },
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject. In this list it is set only on the `email.submitted` row; `GET /email-logs/{event}` returns it for any event."
                                                                },
                                                                "from": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "email": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "The sending address. In this list it is set only on the `email.submitted` row, as with `subject`."
                                                                        },
                                                                        "name": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "The sender's display name. Null when there is none, or on a list row that is not `email.submitted`."
                                                                        }
                                                                    }
                                                                },
                                                                "tags": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Your labels from the send. `[]` means the message had no tags. Null means this row is not `email.submitted`, so the tags are not shown here."
                                                                },
                                                                "metadata": {
                                                                    "type": "object",
                                                                    "nullable": true,
                                                                    "additionalProperties": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "The metadata you set when sending, returned unchanged on every event for this message. `{}` means there was none. Null means this row is not `email.submitted`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body as sent. Null when the message was text only, or we never saw it being sent."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body as sent. Null when there was none, or we never saw it being sent."
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When we recorded the event, which can be a little after it happened."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "delete": {
                "operationId": "deleteEmailLogsEvent",
                "summary": "Delete a delivery event",
                "tags": [
                    "Events"
                ],
                "x-required-scope": "suppressions:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "event",
                        "in": "path",
                        "required": true,
                        "description": "The event identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The event is erased from the log; the message's other events are untouched, so a timeline can be left with a hole in it."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Removes an event from the log. Requires a write scope: a key issued for reporting must not be able to erase the history it reports on."
            }
        },
        "/api/v1/email-logs/{event}/resend": {
            "post": {
                "operationId": "postEmailLogsEventResend",
                "summary": "Resend a message",
                "tags": [
                    "Events"
                ],
                "x-required-scope": "messages:send",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "event",
                        "in": "path",
                        "required": true,
                        "description": "The event identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "message"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Mailyte's ID for this message: a ULID such as `01JBT8XQ2M9WYC3K4F6R7S8T9V`, without angle brackets. Look it up right away with `GET /email-logs/messages/{id}`. It is not the Message-ID header."
                                                        },
                                                        "message_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Message-ID header as sent, angle brackets included, such as `<01JBT8XQ2M\u2026@example.com>`. Use it, percent-encoded, with `GET /domains/{domain}/messages/{messageId}`. It is not the same as `id`."
                                                        },
                                                        "recipient": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The first recipient's address, without a display name. Read `recipients` for everyone the message was sent to."
                                                        },
                                                        "recipients": {
                                                            "type": "object",
                                                            "description": "Everyone the message was addressed to. Bcc recipients are never listed here; they appear only in your delivery log.",
                                                            "properties": {
                                                                "to": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "As accepted, including any display name."
                                                                },
                                                                "cc": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Empty when there were no cc recipients."
                                                                },
                                                                "count": {
                                                                    "type": "integer",
                                                                    "description": "To plus Cc. Excludes Bcc, which is not published here; the limit of 50 counts all three together."
                                                                }
                                                            }
                                                        },
                                                        "reply_to": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Reply-To address sent. Null when none was set; replies then go to `from`."
                                                        },
                                                        "attachment_count": {
                                                            "type": "integer",
                                                            "description": "How many files were attached."
                                                        },
                                                        "from": {
                                                            "type": "object",
                                                            "description": "The sender. An object here, and everywhere else a sender appears, so one piece of caller code reads all of them.",
                                                            "properties": {
                                                                "email": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The address the message was sent from."
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The display name in the `From:` header. Null when the sender has no display name, so the message went out as a bare address."
                                                                }
                                                            }
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The subject as sent, with `{{ }}` variables filled in. An empty subject is `\"\"`, never null."
                                                        },
                                                        "submitted_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When we accepted the message. This is not delivery: a 200 means queued, and the outcome arrives as a delivery event or a webhook."
                                                        },
                                                        "mode": {
                                                            "type": "string",
                                                            "enum": [
                                                                "live",
                                                                "test"
                                                            ],
                                                            "description": "`live` for a real send. `test` when the request used a test API key (`mk_test_\u2026`): the message was checked and built like a real one, then stored in your Sandbox instead of being delivered. Read it with `GET /sandbox/messages/{id}`. Test sends skip suppression and rate limits, and fire no live webhooks."
                                                        },
                                                        "sandbox": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Where a test send was stored. Null for a live send.",
                                                            "properties": {
                                                                "message_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sandbox message id, for `GET /sandbox/messages/{id}`. Not the same as `id`: that is the Message-ID local part the message carries, this is the sandbox's own record of it."
                                                                },
                                                                "inbox_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The inbox it landed in: your default sandbox inbox, created for you on the first test send if you had none."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Submits the stored copy of this message again. Requires `messages:send`, not\n`events:read` \u2014 it puts mail back on the wire.\n\nPass `to` to send it somewhere else. That is the usual reason to resend: the customer\ngave the wrong address, and reconstructing the message by hand to send it to the right\none loses whatever the original actually said.\n\nA redirected resend is not a privileged path \u2014 the new recipient is checked against\nyour suppression list and counted against your rate limit exactly like a fresh send.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "to": {
                                        "oneOf": [
                                            {
                                                "type": "string"
                                            },
                                            {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                }
                                            }
                                        ],
                                        "description": "Send to this address instead of the original recipient. Omit to resend to whoever it went to the first time."
                                    }
                                }
                            },
                            "example": {
                                "to": "corrected@example.com"
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/email-suppressions": {
            "get": {
                "operationId": "getEmailSuppressions",
                "summary": "List suppressed addresses",
                "tags": [
                    "Suppressions"
                ],
                "x-required-scope": "suppressions:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "suppression"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "email": {
                                                                        "type": "string",
                                                                        "description": "The address, or the bare domain when `scope` is `domain`. Always lowercase."
                                                                    },
                                                                    "scope": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "address",
                                                                            "domain"
                                                                        ],
                                                                        "description": "A `domain` rule blocks every recipient at that EXACT domain. Subdomains are separate rules, matching SendGrid and Mailgun, so a rule never blocks more than the string somebody typed."
                                                                    },
                                                                    "applies_to": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "all",
                                                                            "marketing"
                                                                        ],
                                                                        "description": "What this blocks. `all` stops every email, including app email such as receipts and password resets. `marketing` stops only marketing. An unsubscribe blocks marketing; a bounce or complaint blocks everything."
                                                                    },
                                                                    "reason": {
                                                                        "type": "string",
                                                                        "description": "Why the address is blocked: usually `unsubscribed`, `complained`, `bounced` or `manual`. Imported rows can carry other values (`import` by default), so do not treat this as a closed list."
                                                                    },
                                                                    "source": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "manual",
                                                                            "automatic"
                                                                        ],
                                                                        "description": "`manual` is a person or your API call; `automatic` is our bounce and complaint listener. A manual entry is never downgraded to automatic by a later event."
                                                                    },
                                                                    "note": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Your own note. Null when none was written; entries we add automatically have none."
                                                                    },
                                                                    "suppressed_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the address was blocked."
                                                                    },
                                                                    "expires_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the block ends and the address can be emailed again. Null means never, which is the case for everything you add and for every bounce, complaint and unsubscribe. The one block that ends: a mailbox that stayed full for three days is skipped for 30."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Addresses Mailyte will refuse to send to, and why.\n\nSuppressions are enforced ahead of your own list logic \u2014 removing someone from your\ndatabase does not remove them from here, and adding them back in your database does\nnot resurrect them here. This is what keeps a hard bounce from being retried into a\nreputation problem."
            },
            "post": {
                "operationId": "postEmailSuppressions",
                "summary": "Create a email suppression",
                "tags": [
                    "Suppressions"
                ],
                "x-required-scope": "suppressions:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "suppression"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "description": "The address, or the bare domain when `scope` is `domain`. Always lowercase."
                                                        },
                                                        "scope": {
                                                            "type": "string",
                                                            "enum": [
                                                                "address",
                                                                "domain"
                                                            ],
                                                            "description": "A `domain` rule blocks every recipient at that EXACT domain. Subdomains are separate rules, matching SendGrid and Mailgun, so a rule never blocks more than the string somebody typed."
                                                        },
                                                        "applies_to": {
                                                            "type": "string",
                                                            "enum": [
                                                                "all",
                                                                "marketing"
                                                            ],
                                                            "description": "What this blocks. `all` stops every email, including app email such as receipts and password resets. `marketing` stops only marketing. An unsubscribe blocks marketing; a bounce or complaint blocks everything."
                                                        },
                                                        "reason": {
                                                            "type": "string",
                                                            "description": "Why the address is blocked: usually `unsubscribed`, `complained`, `bounced` or `manual`. Imported rows can carry other values (`import` by default), so do not treat this as a closed list."
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "enum": [
                                                                "manual",
                                                                "automatic"
                                                            ],
                                                            "description": "`manual` is a person or your API call; `automatic` is our bounce and complaint listener. A manual entry is never downgraded to automatic by a later event."
                                                        },
                                                        "note": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your own note. Null when none was written; entries we add automatically have none."
                                                        },
                                                        "suppressed_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the address was blocked."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the block ends and the address can be emailed again. Null means never, which is the case for everything you add and for every bounce, complaint and unsubscribe. The one block that ends: a mailbox that stayed full for three days is skipped for 30."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "enum": [
                                            "unsubscribed",
                                            "complained",
                                            "bounced",
                                            "manual"
                                        ],
                                        "description": "Why they are blocked.",
                                        "example": "unsubscribed"
                                    },
                                    "email": {
                                        "type": "string",
                                        "description": "The address to block. With `scope: domain`, a domain like `example.com` (no @).",
                                        "example": "ada@example.com"
                                    },
                                    "scope": {
                                        "type": "string",
                                        "enum": [
                                            "address",
                                            "domain"
                                        ],
                                        "description": "`address` (the default) blocks one address. `domain` blocks every address at a domain."
                                    },
                                    "note": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Optional. Your own note on why."
                                    }
                                },
                                "required": [
                                    "reason",
                                    "email"
                                ]
                            },
                            "example": {
                                "reason": "unsubscribed",
                                "email": "ada@example.com"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/email-suppressions/import": {
            "post": {
                "operationId": "postEmailSuppressionsImport",
                "summary": "Import suppressed addresses",
                "tags": [
                    "Suppressions"
                ],
                "x-required-scope": "suppressions:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "suppression_import"
                                                            ]
                                                        },
                                                        "imported": {
                                                            "type": "integer",
                                                            "description": "Addresses newly suppressed by this call."
                                                        },
                                                        "skipped": {
                                                            "type": "object",
                                                            "description": "Two causes, one category, and a caller deciding whether to re-upload cares about them very differently.",
                                                            "properties": {
                                                                "invalid": {
                                                                    "type": "integer",
                                                                    "description": "Rows that were not addresses. Your file has typos; a 10,000-row list with three of them imports 9,997. An invalid row is never a rejected request."
                                                                },
                                                                "duplicate": {
                                                                    "type": "integer",
                                                                    "description": "Rows already suppressed. Nothing is wrong. Derived from the database's own insert count rather than a pre-check, so it stays exact under a concurrent writer."
                                                                }
                                                            }
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Rows read. Always equal to `imported` + `skipped.invalid` + `skipped.duplicate`."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Block up to 10,000 addresses in one request, for example the unsubscribes you are bringing\nover from another email service. Mailyte will not send to them again until you remove them.\n\nAn invalid address is skipped and counted, never fatal. An address that is already\nsuppressed, or appears twice in the request, is counted once. To block a whole domain, use\n`POST /email-suppressions` with `\"scope\": \"domain\"`.\n\n**Two ways to send addresses.** Send JSON with an `emails` array, as in the example below.\nOr upload a CSV file as a form (`multipart/form-data`) in a field called `file`, with one\naddress per row in the first column (a header row is fine):\n\n```bash\ncurl -X POST 'https://app.mailyte.com/api/v1/email-suppressions/import' \\\n  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \\\n  -F 'file=@unsubscribes.csv' \\\n  -F 'reason=unsubscribed'\n```\n\nSend `file` or `emails`, not both.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "emails"
                                ],
                                "properties": {
                                    "emails": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 10000,
                                        "items": {
                                            "type": "string",
                                            "format": "email"
                                        },
                                        "description": "The addresses to block, 1 to 10,000 per request.",
                                        "x-example": [
                                            "ada@example.com"
                                        ]
                                    },
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 30,
                                        "description": "Optional. Why they are blocked, shown beside each address in the list, for example `unsubscribed` or `bounced`. Defaults to `import`."
                                    }
                                }
                            },
                            "example": {
                                "emails": [
                                    "ada@example.com",
                                    "tunde@example.com"
                                ],
                                "reason": "unsubscribed"
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/email-suppressions/{suppression}": {
            "delete": {
                "operationId": "deleteEmailSuppressionsSuppression",
                "summary": "Remove a suppression",
                "tags": [
                    "Suppressions"
                ],
                "x-required-scope": "suppressions:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "suppression",
                        "in": "path",
                        "required": true,
                        "description": "The suppression identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "Nothing. The address can be emailed again. Only remove a block when you know the cause is gone."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Allows sending to this address again.\n\nWorth doing only when you know why it was suppressed and that the cause is gone \u2014 a\nfixed typo, a mailbox that has been recreated. Removing a spam complaint because you\nwould rather keep sending is how a sending reputation is lost."
            }
        },
        "/api/v1/verifications": {
            "get": {
                "operationId": "getVerifications",
                "summary": "List verifications",
                "tags": [
                    "Verification"
                ],
                "x-required-scope": "verification:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Page size, 1\u2013100. Default 25.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "verification"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "running",
                                                                            "finished",
                                                                            "expired",
                                                                            "failed"
                                                                        ],
                                                                        "description": "`running` until every address has an answer, then `finished`. `expired`: the checker could not answer some addresses within a day; they stay `pending` and their checks or credits were given back."
                                                                    },
                                                                    "source": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "list",
                                                                            "contacts",
                                                                            "import",
                                                                            "campaign",
                                                                            "automatic",
                                                                            "single"
                                                                        ],
                                                                        "description": "Where the addresses came from:\n\n- `list`: addresses you sent (1 check each; older runs used send credits).\n- `contacts`: your contacts that were never checked (free).\n- `import`, `campaign`: checks we run when you import contacts or start a campaign (free).\n- `automatic`: the day's checks of new contacts while Bounce protection is on.\n- `single`: the day's one-address checks."
                                                                    },
                                                                    "label": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "total": {
                                                                        "type": "integer",
                                                                        "description": "Unique addresses in the run."
                                                                    },
                                                                    "counts": {
                                                                        "type": "object",
                                                                        "description": "Always sums to `total`.",
                                                                        "properties": {
                                                                            "valid": {
                                                                                "type": "integer",
                                                                                "minimum": 0,
                                                                                "description": "The mailbox exists."
                                                                            },
                                                                            "invalid": {
                                                                                "type": "integer",
                                                                                "minimum": 0,
                                                                                "description": "Does not exist, cannot receive mail, or is not an address. Mail to these is refused."
                                                                            },
                                                                            "risky": {
                                                                                "type": "integer",
                                                                                "minimum": 0,
                                                                                "description": "Throwaway, catch-all or role address: may not reach a person."
                                                                            },
                                                                            "unknown": {
                                                                                "type": "integer",
                                                                                "minimum": 0,
                                                                                "description": "The provider would not confirm either way (Yahoo and AOL never do). Sent as normal."
                                                                            },
                                                                            "pending": {
                                                                                "type": "integer",
                                                                                "minimum": 0,
                                                                                "description": "Still being checked."
                                                                            }
                                                                        }
                                                                    },
                                                                    "credits_charged": {
                                                                        "type": "integer",
                                                                        "description": "Send credits this run cost (older runs, or checks paid from credits bought or granted before launch, at 10 credits a check)."
                                                                    },
                                                                    "credits_refunded": {
                                                                        "type": "integer",
                                                                        "description": "Send credits given back."
                                                                    },
                                                                    "checks_charged": {
                                                                        "type": "integer",
                                                                        "description": "Checks drawn for this run."
                                                                    },
                                                                    "checks_refunded": {
                                                                        "type": "integer",
                                                                        "description": "Checks given back (couldn't confirm, or never answered)."
                                                                    },
                                                                    "charge_unit": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "description": "`checks`, or null for a run paid in send credits."
                                                                    },
                                                                    "by_mailyte": {
                                                                        "type": "boolean",
                                                                        "description": "True for a free check Mailyte ran on your contacts, such as the one-time check of existing contacts at launch."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "finished_at": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postVerifications",
                "summary": "Verify a list of addresses",
                "tags": [
                    "Verification"
                ],
                "x-required-scope": "verification:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "description": "Makes this request safe to retry. Use `<app>-<ULID>`, such as `crm-01JBT8XQ2M9WYC3K4F6R7S8T9V`; any other shape is a 422. Send the same key on every retry: a repeat gets the first answer with `Idempotency-Replayed: true`, a key reused for a different request is a 422, and one still running is a 409 with `Retry-After`. Keys last 24 hours, per organization.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z][a-z0-9]{0,19}-[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
                            "example": "crm-01JBT8XQ2M9WYC3K4F6R7S8T9V"
                        }
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Started. Poll the verification until `status` is `finished`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "verification"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "running",
                                                                "finished",
                                                                "expired",
                                                                "failed"
                                                            ],
                                                            "description": "`running` until every address has an answer, then `finished`. `expired`: the checker could not answer some addresses within a day; they stay `pending` and their checks or credits were given back."
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "enum": [
                                                                "list",
                                                                "contacts",
                                                                "import",
                                                                "campaign",
                                                                "automatic",
                                                                "single"
                                                            ],
                                                            "description": "Where the addresses came from:\n\n- `list`: addresses you sent (1 check each; older runs used send credits).\n- `contacts`: your contacts that were never checked (free).\n- `import`, `campaign`: checks we run when you import contacts or start a campaign (free).\n- `automatic`: the day's checks of new contacts while Bounce protection is on.\n- `single`: the day's one-address checks."
                                                        },
                                                        "label": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Unique addresses in the run."
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "description": "Always sums to `total`.",
                                                            "properties": {
                                                                "valid": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "The mailbox exists."
                                                                },
                                                                "invalid": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Does not exist, cannot receive mail, or is not an address. Mail to these is refused."
                                                                },
                                                                "risky": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Throwaway, catch-all or role address: may not reach a person."
                                                                },
                                                                "unknown": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "The provider would not confirm either way (Yahoo and AOL never do). Sent as normal."
                                                                },
                                                                "pending": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Still being checked."
                                                                }
                                                            }
                                                        },
                                                        "credits_charged": {
                                                            "type": "integer",
                                                            "description": "Send credits this run cost (older runs, or checks paid from credits bought or granted before launch, at 10 credits a check)."
                                                        },
                                                        "credits_refunded": {
                                                            "type": "integer",
                                                            "description": "Send credits given back."
                                                        },
                                                        "checks_charged": {
                                                            "type": "integer",
                                                            "description": "Checks drawn for this run."
                                                        },
                                                        "checks_refunded": {
                                                            "type": "integer",
                                                            "description": "Checks given back (couldn't confirm, or never answered)."
                                                        },
                                                        "charge_unit": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "`checks`, or null for a run paid in send credits."
                                                        },
                                                        "by_mailyte": {
                                                            "type": "boolean",
                                                            "description": "True for a free check Mailyte ran on your contacts, such as the one-time check of existing contacts at launch."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "finished_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Checks whether each address has a mailbox \u2014 **without sending anything**. We ask the\nrecipient's mail server directly, the way a sending server would, and stop before any\nmessage is sent.\n\nUses **one check per unique address**, taken when the verification starts: this month's\nplan checks first, then checks you bought, then send credits bought before checks launched\n(10 credits a check). Duplicates and letter case are removed first, so `Ada@x.com` and\n`ada@x.com` are one address. If you have fewer checks than the list needs, nothing starts\nand nothing is used: a `402` whose `data.quote` says how many you need and which pack\ncovers the rest. An address we could not confirm gives its check back. The reply carries\n`X-Mailyte-Checks-Remaining`.\n\nBefore checks launch on your account, a list is paid in send credits instead, priced by its\nsize, after the list checks your plan includes this month; with too few credits nothing\nstarts (a `402`).\n\nMost answers arrive within seconds. Gmail mailboxes are checked at a steady pace, so a large\nlist can take a while; addresses still being checked read `pending`. Anything we cannot\nanswer within a day is refunded.\n\nSend an `Idempotency-Key` header so a retried request is never charged twice. Up to\n**50,000** addresses per verification, and up to 3 running at once.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "emails"
                                ],
                                "properties": {
                                    "emails": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 50000,
                                        "items": {
                                            "type": "string",
                                            "maxLength": 320
                                        },
                                        "description": "The addresses to check.",
                                        "x-example": [
                                            "ada@example.com"
                                        ]
                                    },
                                    "label": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Your own name for this verification."
                                    }
                                }
                            },
                            "example": {
                                "emails": [
                                    "ada@example.com"
                                ]
                            }
                        }
                    }
                },
                "x-example-source": "generated"
            }
        },
        "/api/v1/verifications/check": {
            "post": {
                "operationId": "postVerificationsCheck",
                "summary": "Check one address",
                "tags": [
                    "Verification"
                ],
                "x-required-scope": "verification:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "description": "Makes this request safe to retry. Use `<app>-<ULID>`, such as `crm-01JBT8XQ2M9WYC3K4F6R7S8T9V`; any other shape is a 422. Send the same key on every retry: a repeat gets the first answer with `Idempotency-Replayed: true`, a key reused for a different request is a 422, and one still running is a 409 with `Retry-After`. Keys last 24 hours, per organization.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z][a-z0-9]{0,19}-[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
                            "example": "crm-01JBT8XQ2M9WYC3K4F6R7S8T9V"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The answer, or `pending` if it is still being checked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "verification_result"
                                                            ]
                                                        },
                                                        "email": {
                                                            "type": "string"
                                                        },
                                                        "result": {
                                                            "type": "string",
                                                            "enum": [
                                                                "valid",
                                                                "invalid",
                                                                "risky",
                                                                "unknown",
                                                                "pending"
                                                            ],
                                                            "description": "The answer. Mail to `invalid` is refused; `risky` and `unknown` are sent as normal; `pending` is still being checked. `risky` with reason `inbox_full` means the mailbox has no space: while Bounce protection is on, marketing to this contact waits 7 days and the address is checked again."
                                                        },
                                                        "reason": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mailbox_exists",
                                                                "mailbox_does_not_exist",
                                                                "domain_cannot_receive_mail",
                                                                "misspelt_domain",
                                                                "invalid_syntax",
                                                                "disposable_address",
                                                                "accepts_all_addresses",
                                                                "role_address",
                                                                "provider_does_not_confirm",
                                                                "inbox_full",
                                                                "could_not_confirm",
                                                                "checking"
                                                            ]
                                                        },
                                                        "flags": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "role",
                                                                    "disposable",
                                                                    "catch_all",
                                                                    "full"
                                                                ]
                                                            },
                                                            "description": "`role`: info@, sales@ and the like. `disposable`: a throwaway inbox (marketing to it is not sent). `catch_all`: the domain accepts any address. `full`: the mailbox has no space."
                                                        },
                                                        "suggestion": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "For `misspelt_domain` only: the address as it was probably meant (`ada@gmail.con` gives `ada@gmail.com`). Null for every other answer."
                                                        },
                                                        "checks_used": {
                                                            "type": "integer",
                                                            "enum": [
                                                                0,
                                                                1
                                                            ],
                                                            "description": "Present while checks are on: 1 when this answer used a check, 0 when it was free (couldn't confirm, not an email address, or still being checked)."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Checks one address and answers in the same call when it can \u2014 a mailbox we have not seen\nbefore can take a few seconds. Use it at sign-up, before an address goes into your database.\n\nUses **one check**, and only when there is an answer: a `pending` result, \"couldn't confirm\"\nand \"not an email address\" cost nothing; for `pending`, ask again a little later. The\nanswer says which in `checks_used` (`1` when it used a check, `0` when it was free), and the\nreply carries `X-Mailyte-Checks-Remaining`. With no checks left it is a `402` naming the\npack that covers it.\n\nBefore checks launch on your account, an answer costs **10 send credits** (or one of the\nlist checks your plan includes this month) instead, charged only when there is an answer.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "maxLength": 320,
                                        "description": "The address to check.",
                                        "example": "ada@example.com"
                                    }
                                }
                            },
                            "example": {
                                "email": "ada@example.com"
                            }
                        }
                    }
                },
                "x-example-source": "generated"
            }
        },
        "/api/v1/verifications/contacts": {
            "post": {
                "operationId": "postVerificationsContacts",
                "summary": "Verify your unchecked contacts",
                "tags": [
                    "Verification"
                ],
                "x-required-scope": "verification:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "description": "Makes this request safe to retry. Use `<app>-<ULID>`, such as `crm-01JBT8XQ2M9WYC3K4F6R7S8T9V`; any other shape is a 422. Send the same key on every retry: a repeat gets the first answer with `Idempotency-Replayed: true`, a key reused for a different request is a 422, and one still running is a 409 with `Retry-After`. Keys last 24 hours, per organization.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z][a-z0-9]{0,19}-[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
                            "example": "crm-01JBT8XQ2M9WYC3K4F6R7S8T9V"
                        }
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Started.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "verification"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "running",
                                                                "finished",
                                                                "expired",
                                                                "failed"
                                                            ],
                                                            "description": "`running` until every address has an answer, then `finished`. `expired`: the checker could not answer some addresses within a day; they stay `pending` and their checks or credits were given back."
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "enum": [
                                                                "list",
                                                                "contacts",
                                                                "import",
                                                                "campaign",
                                                                "automatic",
                                                                "single"
                                                            ],
                                                            "description": "Where the addresses came from:\n\n- `list`: addresses you sent (1 check each; older runs used send credits).\n- `contacts`: your contacts that were never checked (free).\n- `import`, `campaign`: checks we run when you import contacts or start a campaign (free).\n- `automatic`: the day's checks of new contacts while Bounce protection is on.\n- `single`: the day's one-address checks."
                                                        },
                                                        "label": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Unique addresses in the run."
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "description": "Always sums to `total`.",
                                                            "properties": {
                                                                "valid": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "The mailbox exists."
                                                                },
                                                                "invalid": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Does not exist, cannot receive mail, or is not an address. Mail to these is refused."
                                                                },
                                                                "risky": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Throwaway, catch-all or role address: may not reach a person."
                                                                },
                                                                "unknown": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "The provider would not confirm either way (Yahoo and AOL never do). Sent as normal."
                                                                },
                                                                "pending": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Still being checked."
                                                                }
                                                            }
                                                        },
                                                        "credits_charged": {
                                                            "type": "integer",
                                                            "description": "Send credits this run cost (older runs, or checks paid from credits bought or granted before launch, at 10 credits a check)."
                                                        },
                                                        "credits_refunded": {
                                                            "type": "integer",
                                                            "description": "Send credits given back."
                                                        },
                                                        "checks_charged": {
                                                            "type": "integer",
                                                            "description": "Checks drawn for this run."
                                                        },
                                                        "checks_refunded": {
                                                            "type": "integer",
                                                            "description": "Checks given back (couldn't confirm, or never answered)."
                                                        },
                                                        "charge_unit": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "`checks`, or null for a run paid in send credits."
                                                        },
                                                        "by_mailyte": {
                                                            "type": "boolean",
                                                            "description": "True for a free check Mailyte ran on your contacts, such as the one-time check of existing contacts at launch."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "finished_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        },
                        "headers": {
                            "X-Mailyte-Checks-Remaining": {
                                "description": "The checks your account has left after this request: this month's plan checks, then bought checks, then send credits bought before checks launched, all counted in checks. Sent only once Bounce protection is on for your account.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "X-Mailyte-Checks-Warning": {
                                "description": "`running_low`: at your pace of the last 7 days the checks last under a week, or 80% of this month's plan checks are used and you have none bought. `ran_out`: no checks are left and a new contact this month could not be checked, so it was added as `not_checked`. Absent when neither applies, and until Bounce protection is on for your account.",
                                "schema": {
                                    "type": "string",
                                    "enum": [
                                        "running_low",
                                        "ran_out"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Checks your contacts that have never been checked, newest first, up to `max` (at most\n50,000). Contacts whose address does not exist are marked `bounced` and are never mailed.\n\nOnce Bounce protection is on for your account, it uses **one check per address**, and new\ncontacts are checked as they arrive, so this is for contacts from before, or added while\nBounce protection was off or out of checks. If you have fewer checks than it needs, nothing\nstarts and nothing is used: a `402` whose `data.quote` covers it. An address Mailyte is\nalready asking again by itself (a check that could not confirm yet) is left out, so it is\nnever paid for twice. One such check runs at a time (a second is a `409`); if the checker\ncannot be reached, nothing is used (a `503`). The reply carries\n`X-Mailyte-Checks-Remaining` and, when it applies, `X-Mailyte-Checks-Warning`.\n\nBefore that, it is **free** and checks every never-checked contact; `max` is ignored.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "max": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 50000,
                                        "description": "Check at most this many contacts, newest first. Once Bounce protection is on; ignored before. Default 50,000."
                                    }
                                }
                            },
                            "example": {
                                "max": 2000
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/verifications/{verification}": {
            "get": {
                "operationId": "getVerificationsVerification",
                "summary": "Retrieve a verification",
                "tags": [
                    "Verification"
                ],
                "x-required-scope": "verification:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "verification",
                        "in": "path",
                        "required": true,
                        "description": "The verification identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "verification"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "running",
                                                                "finished",
                                                                "expired",
                                                                "failed"
                                                            ],
                                                            "description": "`running` until every address has an answer, then `finished`. `expired`: the checker could not answer some addresses within a day; they stay `pending` and their checks or credits were given back."
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "enum": [
                                                                "list",
                                                                "contacts",
                                                                "import",
                                                                "campaign",
                                                                "automatic",
                                                                "single"
                                                            ],
                                                            "description": "Where the addresses came from:\n\n- `list`: addresses you sent (1 check each; older runs used send credits).\n- `contacts`: your contacts that were never checked (free).\n- `import`, `campaign`: checks we run when you import contacts or start a campaign (free).\n- `automatic`: the day's checks of new contacts while Bounce protection is on.\n- `single`: the day's one-address checks."
                                                        },
                                                        "label": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Unique addresses in the run."
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "description": "Always sums to `total`.",
                                                            "properties": {
                                                                "valid": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "The mailbox exists."
                                                                },
                                                                "invalid": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Does not exist, cannot receive mail, or is not an address. Mail to these is refused."
                                                                },
                                                                "risky": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Throwaway, catch-all or role address: may not reach a person."
                                                                },
                                                                "unknown": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "The provider would not confirm either way (Yahoo and AOL never do). Sent as normal."
                                                                },
                                                                "pending": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "description": "Still being checked."
                                                                }
                                                            }
                                                        },
                                                        "credits_charged": {
                                                            "type": "integer",
                                                            "description": "Send credits this run cost (older runs, or checks paid from credits bought or granted before launch, at 10 credits a check)."
                                                        },
                                                        "credits_refunded": {
                                                            "type": "integer",
                                                            "description": "Send credits given back."
                                                        },
                                                        "checks_charged": {
                                                            "type": "integer",
                                                            "description": "Checks drawn for this run."
                                                        },
                                                        "checks_refunded": {
                                                            "type": "integer",
                                                            "description": "Checks given back (couldn't confirm, or never answered)."
                                                        },
                                                        "charge_unit": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "`checks`, or null for a run paid in send credits."
                                                        },
                                                        "by_mailyte": {
                                                            "type": "boolean",
                                                            "description": "True for a free check Mailyte ran on your contacts, such as the one-time check of existing contacts at launch."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "finished_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/verifications/{verification}/results": {
            "get": {
                "operationId": "getVerificationsVerificationResults",
                "summary": "Get a verification's results",
                "tags": [
                    "Verification"
                ],
                "x-required-scope": "verification:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "verification",
                        "in": "path",
                        "required": true,
                        "description": "The verification identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "description": "Skip this many answers. Counted over the matches when `q` or `result` is sent. Default 0.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Answers to return, 1\u20135,000. Default 1,000.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Keep the addresses containing this text, ignoring case. A domain finds everyone on it.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "result",
                        "in": "query",
                        "required": false,
                        "description": "Keep only these answers, comma separated: `valid`, `invalid`, `risky`, `unknown`, `pending`. An answer we do not know is a 422.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "description": "`csv` for the whole verification as a download. `q` and `result` do not narrow it.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "verification_result"
                                                                ]
                                                            },
                                                            "email": {
                                                                "type": "string"
                                                            },
                                                            "result": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "valid",
                                                                    "invalid",
                                                                    "risky",
                                                                    "unknown",
                                                                    "pending"
                                                                ],
                                                                "description": "The answer. Mail to `invalid` is refused; `risky` and `unknown` are sent as normal; `pending` is still being checked. `risky` with reason `inbox_full` means the mailbox has no space: while Bounce protection is on, marketing to this contact waits 7 days and the address is checked again."
                                                            },
                                                            "reason": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "mailbox_exists",
                                                                    "mailbox_does_not_exist",
                                                                    "domain_cannot_receive_mail",
                                                                    "misspelt_domain",
                                                                    "invalid_syntax",
                                                                    "disposable_address",
                                                                    "accepts_all_addresses",
                                                                    "role_address",
                                                                    "provider_does_not_confirm",
                                                                    "inbox_full",
                                                                    "could_not_confirm",
                                                                    "checking"
                                                                ]
                                                            },
                                                            "flags": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "role",
                                                                        "disposable",
                                                                        "catch_all",
                                                                        "full"
                                                                    ]
                                                                },
                                                                "description": "`role`: info@, sales@ and the like. `disposable`: a throwaway inbox (marketing to it is not sent). `catch_all`: the domain accepts any address. `full`: the mailbox has no space."
                                                            },
                                                            "suggestion": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "description": "For `misspelt_domain` only: the address as it was probably meant (`ada@gmail.con` gives `ada@gmail.com`). Null for every other answer."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "One answer per address. `result` is what to do: send to `valid`, `risky` and `unknown`; mail\nto `invalid` is refused. `reason` says what was found, never how \u2014 an address known not to\nexist reads the same however we learned it.\n\n`risky` with reason `inbox_full` (and the flag `full`) means the mailbox has no space: mail\nwill bounce until the person clears it. Once Bounce protection is on for your account,\nmarketing to that contact is held for 7 days (`email_full_until` on the contact), then\nchecked again, free.\n\n`q` and `result` narrow the answers before they are paged, so a page is a page of the\nmatches: `?q=techies.africa` finds everyone on that domain, `?result=invalid,risky` keeps\nonly those two answers, and `offset` then counts the matches rather than the whole run.\n\nAdd `format=csv` to download the whole verification as a CSV file instead."
            }
        },
        "/api/v1/verifications/peek": {
            "post": {
                "operationId": "postVerificationsPeek",
                "summary": "Count how many addresses look bad (free)",
                "tags": [
                    "Verification"
                ],
                "x-required-scope": "verification:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "The count. Every accepted request answers 200, fewer than 10 addresses included.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "address_count"
                                                            ]
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Distinct addresses counted."
                                                        },
                                                        "band": {
                                                            "type": "string",
                                                            "enum": [
                                                                "too_few",
                                                                "fewer_than_10",
                                                                "about"
                                                            ],
                                                            "description": "`too_few`: fewer than 10 addresses, so we did not look. `fewer_than_10`: fewer than 10 look bad. `about`: 10 or more look bad, and the numbers say about how many."
                                                        },
                                                        "look_bad_about": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "About how many look bad, rounded down (to tens; to two significant figures from 1,000). Null unless `band` is `about`."
                                                        },
                                                        "look_bad_percent_about": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "The same as a whole percentage of `total`, rounded down. Null unless `band` is `about`."
                                                        },
                                                        "partial": {
                                                            "type": "boolean",
                                                            "description": "True when the checker could not be asked: only broken addresses, misspelt domains and domains that cannot receive mail were counted."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "About how many of these addresses look bad \u2014 invalid, throwaway, or a full inbox we already\nknow of \u2014 **free, and never which ones**. Nothing is probed: the count comes from what we\nalready know and from checks that need no conversation with a mail server.\n\nThe answer is deliberately rough, so a free count never becomes a free answer:\n\n| `band` | When | Numbers |\n|---|---|---|\n| `too_few` | fewer than 10 distinct addresses | none; we do not look |\n| `fewer_than_10` | fewer than 10 look bad | none |\n| `about` | 10 or more look bad | `look_bad_about`: rounded down to tens, or to two significant figures from 1,000 (12,873 \u2192 12,000); `look_bad_percent_about`, rounded down |\n\n`partial: true` means the checker could not be asked, so the count covers only broken\naddresses, misspelt domains and domains that cannot receive mail.\n\nAddresses are counted once, whatever their letter case. Up to **50,000** a request; more is\na `422`. Free, but limited to 30 counts an hour and 100 a UTC day per account (then `429`\nwith `Retry-After`); the same set again within 10 minutes is answered from memory and does\nnot count.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "addresses"
                                ],
                                "properties": {
                                    "addresses": {
                                        "type": "array",
                                        "maxItems": 50000,
                                        "items": {
                                            "type": "string",
                                            "maxLength": 320
                                        },
                                        "description": "The addresses to count. `emails` is accepted as another name for it."
                                    }
                                }
                            },
                            "example": {
                                "addresses": [
                                    "ada@example.com",
                                    "grace@example.org",
                                    "\u2026"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/verifications/summary": {
            "get": {
                "operationId": "getVerificationsSummary",
                "summary": "Contact health",
                "tags": [
                    "Verification"
                ],
                "x-required-scope": "verification:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "How your subscribed contacts stand with checks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "total_subscribed": {
                                                            "type": "integer",
                                                            "description": "Your subscribed contacts: the ones a send would reach."
                                                        },
                                                        "by_status": {
                                                            "type": "object",
                                                            "description": "The subscribed contacts by `email_status`. The seven always add up to `total_subscribed`.",
                                                            "properties": {
                                                                "valid": {
                                                                    "type": "integer"
                                                                },
                                                                "risky": {
                                                                    "type": "integer",
                                                                    "description": "Includes full inboxes."
                                                                },
                                                                "invalid": {
                                                                    "type": "integer"
                                                                },
                                                                "unknown": {
                                                                    "type": "integer"
                                                                },
                                                                "pending": {
                                                                    "type": "integer",
                                                                    "description": "Being checked now."
                                                                },
                                                                "not_checked": {
                                                                    "type": "integer",
                                                                    "description": "Added after Bounce protection launched and not checked."
                                                                },
                                                                "never_checked": {
                                                                    "type": "integer",
                                                                    "description": "A null `email_status`: from before Bounce protection launched."
                                                                }
                                                            }
                                                        },
                                                        "safe_percent": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "`valid` plus `risky`, less the full inboxes being held, as a percentage of `total_subscribed`, rounded down. **Null when fewer than half are checked**, or with no subscribed contacts."
                                                        },
                                                        "not_checked_look_bad_about": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "About how many of the not-checked contacts (`not_checked` and `never_checked`) look bad. `0` means fewer than 10. Null while the count is being made, when the checker could not be asked, or with fewer than 10 to count."
                                                        },
                                                        "recent": {
                                                            "type": "object",
                                                            "properties": {
                                                                "days": {
                                                                    "type": "integer",
                                                                    "enum": [
                                                                        7
                                                                    ]
                                                                },
                                                                "added": {
                                                                    "type": "integer",
                                                                    "description": "Subscribed contacts added in the last 7 days."
                                                                },
                                                                "added_by_app": {
                                                                    "type": "integer",
                                                                    "description": "Of those, added through the API (POST or PUT /contacts)."
                                                                },
                                                                "look_bad_about": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "About how many of them look bad; read as `not_checked_look_bad_about`."
                                                                }
                                                            }
                                                        },
                                                        "not_checked_by_app": {
                                                            "type": "integer",
                                                            "description": "Subscribed contacts added through the API and not checked (null or `not_checked`)."
                                                        },
                                                        "launch_check": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "running",
                                                                "done"
                                                            ],
                                                            "description": "Our one free check of your existing contacts at launch: `running`, `done`, or null when it never ran for your account."
                                                        },
                                                        "launch_progress": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "How far the launch check has got, while `launch_check` is `running`; null otherwise.",
                                                            "properties": {
                                                                "checked": {
                                                                    "type": "integer",
                                                                    "description": "Addresses answered so far, including the ones that don't exist (they are marked Bounced)."
                                                                },
                                                                "total": {
                                                                    "type": "integer",
                                                                    "description": "Addresses the launch check covers in all."
                                                                },
                                                                "does_not_exist": {
                                                                    "type": "integer",
                                                                    "description": "Answers so far that said the address doesn't exist."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "How your **subscribed** contacts stand \u2014 the ones a send would reach; unsubscribed, bounced,\ncomplained and unconfirmed contacts are not counted. Free, and never a probe.\n\n`by_status` splits `total_subscribed` by `email_status`, and its seven keys always add up to\nit: `never_checked` is a null `email_status` (from before Bounce protection launched),\n`not_checked` was added after it and not checked. A full inbox counts under `risky`.\n\n`safe_percent` is `valid` plus `risky`, less the contacts whose full inbox is being held,\nover `total_subscribed`, rounded down. It is **null when fewer than half are checked** \u2014 then\nsay how many are not checked yet instead of a percentage.\n\nThe two `look_bad_about` counts are free counts over the not-checked contacts and over the\nlast 7 days' new ones, rounded as `POST /verifications/peek` rounds them. `0` means fewer\nthan 10; null means we have no count yet (it is made in the background, so ask again in a\nminute), the checker could not be asked, or there are fewer than 10 addresses to count.\n\n`launch_check`: `running` while we check your existing contacts once, free, at launch;\n`done` after; null when that never ran for your account."
            }
        },
        "/api/v1/webhooks": {
            "get": {
                "operationId": "getWebhooks",
                "summary": "List webhooks",
                "tags": [
                    "Webhooks"
                ],
                "x-required-scope": "webhooks:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "webhook"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "description": "Unique identifier for the webhook."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "Your name for the webhook."
                                                            },
                                                            "url": {
                                                                "type": "string",
                                                                "format": "uri",
                                                                "description": "Where we send events. It must be a public HTTPS address."
                                                            },
                                                            "status": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "active",
                                                                    "inactive"
                                                                ],
                                                                "description": "An `inactive` webhook is skipped by the dispatcher. It is not deleted and keeps its delivery history and its secret."
                                                            },
                                                            "events": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "email.accepted",
                                                                        "email.inbound",
                                                                        "email.delivered",
                                                                        "email.bounced",
                                                                        "email.deferred",
                                                                        "email.rejected",
                                                                        "email.dropped",
                                                                        "tracking.open",
                                                                        "tracking.click",
                                                                        "tracking.unsubscribe",
                                                                        "delivery.complaint",
                                                                        "spam.reported",
                                                                        "storage.quota.warning",
                                                                        "storage.quota.exceeded",
                                                                        "contact.checked",
                                                                        "checks.running_low",
                                                                        "checks.ran_out"
                                                                    ]
                                                                },
                                                                "description": "The events this webhook receives. A name not on this list is refused with a 422. `quota.warning` is an older name for `storage.quota.warning` and still works, but do not use it for new webhooks. `contact.checked`, `checks.running_low` and `checks.ran_out` are about your account, not one email, so filters never hold them back; they are sent only while Bounce protection is on."
                                                            },
                                                            "targeting": {
                                                                "type": "object",
                                                                "description": "Which events reach this webhook. A field that is null does not narrow anything.",
                                                                "properties": {
                                                                    "domain": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Only events for this domain, exact match (`acme.com` does not match `notacme.com`). Null means every domain. Always set on an `email.inbound` webhook in an account with more than one domain."
                                                                    },
                                                                    "sender_includes": {
                                                                        "type": "array",
                                                                        "nullable": true,
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "Any-of substring match on the sender. null = not narrowed."
                                                                    },
                                                                    "subject_contains": {
                                                                        "type": "array",
                                                                        "nullable": true,
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "Any-of substring match on the subject. null = not narrowed."
                                                                    },
                                                                    "body_contains": {
                                                                        "type": "array",
                                                                        "nullable": true,
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "Any-of substring match on the body. null = not narrowed."
                                                                    }
                                                                }
                                                            },
                                                            "deliveries": {
                                                                "type": "object",
                                                                "description": "The delivery history, grouped so the numbers cannot disagree.",
                                                                "properties": {
                                                                    "succeeded": {
                                                                        "type": "integer",
                                                                        "description": "Lifetime tally of accepted deliveries."
                                                                    },
                                                                    "failed": {
                                                                        "type": "integer",
                                                                        "description": "Lifetime tally of failed deliveries."
                                                                    },
                                                                    "consecutive_failures": {
                                                                        "type": "integer",
                                                                        "description": "Resets to zero on any success. This is what drives auto-disable, so it answers a different question from `failed`."
                                                                    },
                                                                    "success_rate": {
                                                                        "type": "number",
                                                                        "format": "float",
                                                                        "nullable": true,
                                                                        "description": "The percentage of deliveries that succeeded, 0 to 100. Null when no delivery has been tried yet; show it as \"no deliveries yet\", not as 0."
                                                                    }
                                                                }
                                                            },
                                                            "last_delivered_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true,
                                                                "description": "When a delivery to this webhook last succeeded, in ISO 8601 UTC. Null when none has succeeded yet; check `deliveries` to see whether any were tried."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "description": "ISO 8601 UTC."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postWebhooks",
                "summary": "Create a webhook endpoint",
                "tags": [
                    "Webhooks"
                ],
                "x-required-scope": "webhooks:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "webhook"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the webhook."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the webhook."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri",
                                                            "description": "Where we send events. It must be a public HTTPS address."
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "inactive"
                                                            ],
                                                            "description": "An `inactive` webhook is skipped by the dispatcher. It is not deleted and keeps its delivery history and its secret."
                                                        },
                                                        "events": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "email.accepted",
                                                                    "email.inbound",
                                                                    "email.delivered",
                                                                    "email.bounced",
                                                                    "email.deferred",
                                                                    "email.rejected",
                                                                    "email.dropped",
                                                                    "tracking.open",
                                                                    "tracking.click",
                                                                    "tracking.unsubscribe",
                                                                    "delivery.complaint",
                                                                    "spam.reported",
                                                                    "storage.quota.warning",
                                                                    "storage.quota.exceeded",
                                                                    "contact.checked",
                                                                    "checks.running_low",
                                                                    "checks.ran_out"
                                                                ]
                                                            },
                                                            "description": "The events this webhook receives. A name not on this list is refused with a 422. `quota.warning` is an older name for `storage.quota.warning` and still works, but do not use it for new webhooks. `contact.checked`, `checks.running_low` and `checks.ran_out` are about your account, not one email, so filters never hold them back; they are sent only while Bounce protection is on."
                                                        },
                                                        "targeting": {
                                                            "type": "object",
                                                            "description": "Which events reach this webhook. A field that is null does not narrow anything.",
                                                            "properties": {
                                                                "domain": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Only events for this domain, exact match (`acme.com` does not match `notacme.com`). Null means every domain. Always set on an `email.inbound` webhook in an account with more than one domain."
                                                                },
                                                                "sender_includes": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the sender. null = not narrowed."
                                                                },
                                                                "subject_contains": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the subject. null = not narrowed."
                                                                },
                                                                "body_contains": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the body. null = not narrowed."
                                                                }
                                                            }
                                                        },
                                                        "deliveries": {
                                                            "type": "object",
                                                            "description": "The delivery history, grouped so the numbers cannot disagree.",
                                                            "properties": {
                                                                "succeeded": {
                                                                    "type": "integer",
                                                                    "description": "Lifetime tally of accepted deliveries."
                                                                },
                                                                "failed": {
                                                                    "type": "integer",
                                                                    "description": "Lifetime tally of failed deliveries."
                                                                },
                                                                "consecutive_failures": {
                                                                    "type": "integer",
                                                                    "description": "Resets to zero on any success. This is what drives auto-disable, so it answers a different question from `failed`."
                                                                },
                                                                "success_rate": {
                                                                    "type": "number",
                                                                    "format": "float",
                                                                    "nullable": true,
                                                                    "description": "The percentage of deliveries that succeeded, 0 to 100. Null when no delivery has been tried yet; show it as \"no deliveries yet\", not as 0."
                                                                }
                                                            }
                                                        },
                                                        "last_delivered_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When a delivery to this webhook last succeeded, in ISO 8601 UTC. Null when none has succeeded yet; check `deliveries` to see whether any were tried."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        },
                                                        "secret": {
                                                            "type": "string",
                                                            "description": "The secret for checking our signatures. **Shown only in the response to `POST /webhooks`**, and never again: save it now. If you lose it, delete the webhook and make a new one. Check the signature on every request before you trust it."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Registers a URL to receive delivery events as they happen.\n\nDelivery is **at least once**, so the same event can arrive twice \u2014 key your handling\non the event id and make it idempotent. Events can also arrive out of order; a\n`delivered` before the `accepted` that preceded it is normal and not a bug.\n\nVerify the signature on every request before trusting the body. See\n[Receiving webhooks](/developer/guides/receiving-webhooks) for the full list of events\nand their payloads.\n\n**What an `email.inbound` event carries.** The sender, the recipients and the subject of\nan email that arrived, and for some messages its body. It goes to every webhook in your\naccount that subscribes to it and whose filters it passes \u2014 so an unfiltered webhook gets\nthe incoming mail of every mailbox on every domain in your account, not only the mailbox\nyour integration uses. `domain` narrows it to one domain's mailboxes; there is no filter\nfor a single mailbox, so check the recipient on your side if you need one.\n\n**Incoming mail needs a domain when your account has more than one.** A webhook\nsubscribed to `email.inbound` must then set `domain` (one of yours, exact match). Leaving\nit out answers `422` on `domain` \u2014 on create, on an update that would remove it, and when\nturning an old webhook back on. With one domain it is optional; when you add a second\ndomain, a webhook without one is tied to the domain you had, so it keeps getting exactly\nwhat it got before.\n\n**Filters, three ways, one result.** The domain can be sent as `domain`,\n`filters.domain` or `targeting.domain`; the top-level `domain` wins when it is sent.\n`filters` uses the stored names (`senderIncludes`, `subjectContains`, `bodyContains`);\n`targeting` uses the names the response returns (`sender_includes`, ...), so you can send\nback what you read. Send one of the two, not both. Every call answers with `targeting`:\nread it back to confirm what is applied. **Anything unknown is a `422` that names it** \u2014\na field, a filter key, or an event name \u2014 never a `200` that quietly ignored it.\n\n**`email.deferred` usually means we are still trying.** The receiving server asked us to\nwait, the message is in our queue, and we retry it for you. One is not ours to retry: when\na marketing SMTP key sends to a contact whose inbox is full and Bounce protection is\nholding marketing to them, the message is refused before it is queued (a `452` that names\na date). It is logged `deferred`, but Mailyte never queued it, so your app must send it\nagain after the date in the `reason`.\n\n**Three account events** are about your account, not about a message, so a webhook's\ndomain, sender, subject and body filters never hold them back. They are sent only once\nBounce protection is on for your account.\n\n- `contact.checked`: a contact's address was checked and the answer changed, once per\n  change. `{contact_id, email, email_status, reason, suggestion, checked_at,\n  email_full_until}`. `email_status` is the contact's new value; `reason` and\n  `suggestion` read as on a verification result (`suggestion` is the corrected address\n  for a misspelt domain, else null). `unknown` with a checker that could not confirm yet\n  is asked again later and may be announced again. `email_full_until` is the end of a\n  hold on marketing to a full inbox while it runs, else null.\n- `checks.running_low`: `{trigger, plan_left, bought, credit_fallback, forecast_days}`.\n  `trigger` is `forecast` (under 7 days of checks left at your recent pace) or `plan_80`\n  (80% of this month's plan checks used, and none bought). The counts are checks, as on\n  `GET /billing/usage`.\n- `checks.ran_out`: `{since, buy_path}`. A new contact could not be checked because no\n  checks were left; it was added as `not_checked`. `buy_path` is the dashboard page that\n  buys the checks we suggest.\n\nThe two `checks.*` events are sent at most once per cycle: a new month, a purchase or\nchecks added by us start a new one.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Production events`.",
                                        "example": "Production events",
                                        "x-example": "Spring newsletter"
                                    },
                                    "events": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "email.accepted",
                                                "email.inbound",
                                                "email.delivered",
                                                "email.bounced",
                                                "email.deferred",
                                                "email.rejected",
                                                "email.dropped",
                                                "tracking.open",
                                                "tracking.click",
                                                "tracking.unsubscribe",
                                                "delivery.complaint",
                                                "spam.reported",
                                                "storage.quota.warning",
                                                "storage.quota.exceeded",
                                                "contact.checked",
                                                "checks.running_low",
                                                "checks.ran_out"
                                            ]
                                        },
                                        "description": "The events to receive. Each one's payload is in the Receiving webhooks guide.",
                                        "example": [
                                            "email.delivered",
                                            "email.bounced"
                                        ]
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 2048,
                                        "description": "The full HTTPS address we send to. It must be reachable from the internet.",
                                        "x-example": "https://example.com/webhooks/mailyte"
                                    },
                                    "filters": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "domain": {
                                                "type": "string",
                                                "description": "The same as the top-level `domain`.",
                                                "x-example": "yourdomain.com"
                                            },
                                            "senderIncludes": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "Only mail whose sender contains one of these."
                                            },
                                            "subjectContains": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "Only mail whose subject contains one of these."
                                            },
                                            "bodyContains": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "Only mail whose body contains one of these."
                                            }
                                        },
                                        "description": "Optional. Send only some events, by what is in the email. A list matches if any of its words appears (case does not matter); leave a list out to match everything. Other keys are refused with a 422. On update this replaces all the filters; leave it out to keep them."
                                    },
                                    "targeting": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "domain": {
                                                "type": "string",
                                                "description": "The same as the top-level `domain`.",
                                                "x-example": "yourdomain.com"
                                            },
                                            "sender_includes": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "As `filters.senderIncludes`."
                                            },
                                            "subject_contains": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "As `filters.subjectContains`."
                                            },
                                            "body_contains": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "As `filters.bodyContains`."
                                            }
                                        },
                                        "description": "The same filters, spelt as the response returns them, so you can send back what you read. Send `filters` or `targeting`, not both."
                                    },
                                    "domain": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 253,
                                        "description": "Only events for this domain, such as `yourdomain.com`: one of your domains, exact match. Required with `email.inbound` when your account has more than one domain. Can also be sent as `filters.domain` or `targeting.domain`; this field wins.",
                                        "x-example": "yourdomain.com"
                                    }
                                },
                                "required": [
                                    "name",
                                    "events",
                                    "url"
                                ]
                            },
                            "example": {
                                "name": "Production events",
                                "events": [
                                    "email.delivered",
                                    "email.bounced"
                                ],
                                "url": "https://example.com/webhooks/mailyte"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            }
        },
        "/api/v1/webhooks/{webhook}": {
            "put": {
                "operationId": "putWebhooksWebhook",
                "summary": "Update a webhook",
                "tags": [
                    "Webhooks"
                ],
                "x-required-scope": "webhooks:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "webhook",
                        "in": "path",
                        "required": true,
                        "description": "The webhook identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "webhook"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the webhook."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the webhook."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri",
                                                            "description": "Where we send events. It must be a public HTTPS address."
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "inactive"
                                                            ],
                                                            "description": "An `inactive` webhook is skipped by the dispatcher. It is not deleted and keeps its delivery history and its secret."
                                                        },
                                                        "events": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "email.accepted",
                                                                    "email.inbound",
                                                                    "email.delivered",
                                                                    "email.bounced",
                                                                    "email.deferred",
                                                                    "email.rejected",
                                                                    "email.dropped",
                                                                    "tracking.open",
                                                                    "tracking.click",
                                                                    "tracking.unsubscribe",
                                                                    "delivery.complaint",
                                                                    "spam.reported",
                                                                    "storage.quota.warning",
                                                                    "storage.quota.exceeded",
                                                                    "contact.checked",
                                                                    "checks.running_low",
                                                                    "checks.ran_out"
                                                                ]
                                                            },
                                                            "description": "The events this webhook receives. A name not on this list is refused with a 422. `quota.warning` is an older name for `storage.quota.warning` and still works, but do not use it for new webhooks. `contact.checked`, `checks.running_low` and `checks.ran_out` are about your account, not one email, so filters never hold them back; they are sent only while Bounce protection is on."
                                                        },
                                                        "targeting": {
                                                            "type": "object",
                                                            "description": "Which events reach this webhook. A field that is null does not narrow anything.",
                                                            "properties": {
                                                                "domain": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Only events for this domain, exact match (`acme.com` does not match `notacme.com`). Null means every domain. Always set on an `email.inbound` webhook in an account with more than one domain."
                                                                },
                                                                "sender_includes": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the sender. null = not narrowed."
                                                                },
                                                                "subject_contains": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the subject. null = not narrowed."
                                                                },
                                                                "body_contains": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the body. null = not narrowed."
                                                                }
                                                            }
                                                        },
                                                        "deliveries": {
                                                            "type": "object",
                                                            "description": "The delivery history, grouped so the numbers cannot disagree.",
                                                            "properties": {
                                                                "succeeded": {
                                                                    "type": "integer",
                                                                    "description": "Lifetime tally of accepted deliveries."
                                                                },
                                                                "failed": {
                                                                    "type": "integer",
                                                                    "description": "Lifetime tally of failed deliveries."
                                                                },
                                                                "consecutive_failures": {
                                                                    "type": "integer",
                                                                    "description": "Resets to zero on any success. This is what drives auto-disable, so it answers a different question from `failed`."
                                                                },
                                                                "success_rate": {
                                                                    "type": "number",
                                                                    "format": "float",
                                                                    "nullable": true,
                                                                    "description": "The percentage of deliveries that succeeded, 0 to 100. Null when no delivery has been tried yet; show it as \"no deliveries yet\", not as 0."
                                                                }
                                                            }
                                                        },
                                                        "last_delivered_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When a delivery to this webhook last succeeded, in ISO 8601 UTC. Null when none has succeeded yet; check `deliveries` to see whether any were tried."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Changes only the fields you send; everything you leave out stays as it is.\n\n`filters` (or `targeting`) replaces **all** of the webhook's filters: a list you leave out\nof it is cleared. Send `domain` on its own to change just the domain and keep the rest.\n`\"filters\": null` clears every filter, the domain included.\n\nThe same rules as create apply: an unknown field, filter key or event name is a `422` that\nnames it, and in an account with more than one domain an update that would leave an\n`email.inbound` webhook without a domain is refused. The response's `targeting` is what is\nnow applied.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Production events`.",
                                        "example": "Production events",
                                        "x-example": "Spring newsletter"
                                    },
                                    "events": {
                                        "nullable": true,
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "email.accepted",
                                                "email.inbound",
                                                "email.delivered",
                                                "email.bounced",
                                                "email.deferred",
                                                "email.rejected",
                                                "email.dropped",
                                                "tracking.open",
                                                "tracking.click",
                                                "tracking.unsubscribe",
                                                "delivery.complaint",
                                                "spam.reported",
                                                "storage.quota.warning",
                                                "storage.quota.exceeded",
                                                "contact.checked",
                                                "checks.running_low",
                                                "checks.ran_out"
                                            ]
                                        },
                                        "description": "The events to receive. Each one's payload is in the Receiving webhooks guide.",
                                        "example": [
                                            "email.delivered",
                                            "email.bounced"
                                        ]
                                    },
                                    "filters": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "domain": {
                                                "type": "string",
                                                "description": "The same as the top-level `domain`.",
                                                "x-example": "yourdomain.com"
                                            },
                                            "senderIncludes": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "Only mail whose sender contains one of these."
                                            },
                                            "subjectContains": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "Only mail whose subject contains one of these."
                                            },
                                            "bodyContains": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "Only mail whose body contains one of these."
                                            }
                                        },
                                        "description": "Optional. Send only some events, by what is in the email. A list matches if any of its words appears (case does not matter); leave a list out to match everything. Other keys are refused with a 422. On update this replaces all the filters; leave it out to keep them."
                                    },
                                    "targeting": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "domain": {
                                                "type": "string",
                                                "description": "The same as the top-level `domain`.",
                                                "x-example": "yourdomain.com"
                                            },
                                            "sender_includes": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "As `filters.senderIncludes`."
                                            },
                                            "subject_contains": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "As `filters.subjectContains`."
                                            },
                                            "body_contains": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "description": "As `filters.bodyContains`."
                                            }
                                        },
                                        "description": "The same filters, spelt as the response returns them, so you can send back what you read. Send `filters` or `targeting`, not both."
                                    },
                                    "domain": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 253,
                                        "description": "Only events for this domain, such as `yourdomain.com`: one of your domains, exact match. Required with `email.inbound` when your account has more than one domain. Can also be sent as `filters.domain` or `targeting.domain`; this field wins.",
                                        "x-example": "yourdomain.com"
                                    },
                                    "url": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 2048,
                                        "description": "The full HTTPS address we send to. It must be reachable from the internet.",
                                        "x-example": "https://example.com/webhooks/mailyte"
                                    }
                                }
                            },
                            "example": {
                                "name": "Production events",
                                "events": [
                                    "email.delivered",
                                    "email.bounced"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteWebhooksWebhook",
                "summary": "Delete a webhook",
                "tags": [
                    "Webhooks"
                ],
                "x-required-scope": "webhooks:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "webhook",
                        "in": "path",
                        "required": true,
                        "description": "The webhook identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No body. The webhook stops receiving events immediately and its signing secret is discarded with it. This is the recovery path for a lost secret: delete the webhook and create a new one."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/webhooks/{webhook}/toggle": {
            "post": {
                "operationId": "postWebhooksWebhookToggle",
                "summary": "Toggle a webhook",
                "tags": [
                    "Webhooks"
                ],
                "x-required-scope": "webhooks:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "webhook",
                        "in": "path",
                        "required": true,
                        "description": "The webhook identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "webhook"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the webhook."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your name for the webhook."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri",
                                                            "description": "Where we send events. It must be a public HTTPS address."
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "inactive"
                                                            ],
                                                            "description": "An `inactive` webhook is skipped by the dispatcher. It is not deleted and keeps its delivery history and its secret."
                                                        },
                                                        "events": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "email.accepted",
                                                                    "email.inbound",
                                                                    "email.delivered",
                                                                    "email.bounced",
                                                                    "email.deferred",
                                                                    "email.rejected",
                                                                    "email.dropped",
                                                                    "tracking.open",
                                                                    "tracking.click",
                                                                    "tracking.unsubscribe",
                                                                    "delivery.complaint",
                                                                    "spam.reported",
                                                                    "storage.quota.warning",
                                                                    "storage.quota.exceeded",
                                                                    "contact.checked",
                                                                    "checks.running_low",
                                                                    "checks.ran_out"
                                                                ]
                                                            },
                                                            "description": "The events this webhook receives. A name not on this list is refused with a 422. `quota.warning` is an older name for `storage.quota.warning` and still works, but do not use it for new webhooks. `contact.checked`, `checks.running_low` and `checks.ran_out` are about your account, not one email, so filters never hold them back; they are sent only while Bounce protection is on."
                                                        },
                                                        "targeting": {
                                                            "type": "object",
                                                            "description": "Which events reach this webhook. A field that is null does not narrow anything.",
                                                            "properties": {
                                                                "domain": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Only events for this domain, exact match (`acme.com` does not match `notacme.com`). Null means every domain. Always set on an `email.inbound` webhook in an account with more than one domain."
                                                                },
                                                                "sender_includes": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the sender. null = not narrowed."
                                                                },
                                                                "subject_contains": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the subject. null = not narrowed."
                                                                },
                                                                "body_contains": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Any-of substring match on the body. null = not narrowed."
                                                                }
                                                            }
                                                        },
                                                        "deliveries": {
                                                            "type": "object",
                                                            "description": "The delivery history, grouped so the numbers cannot disagree.",
                                                            "properties": {
                                                                "succeeded": {
                                                                    "type": "integer",
                                                                    "description": "Lifetime tally of accepted deliveries."
                                                                },
                                                                "failed": {
                                                                    "type": "integer",
                                                                    "description": "Lifetime tally of failed deliveries."
                                                                },
                                                                "consecutive_failures": {
                                                                    "type": "integer",
                                                                    "description": "Resets to zero on any success. This is what drives auto-disable, so it answers a different question from `failed`."
                                                                },
                                                                "success_rate": {
                                                                    "type": "number",
                                                                    "format": "float",
                                                                    "nullable": true,
                                                                    "description": "The percentage of deliveries that succeeded, 0 to 100. Null when no delivery has been tried yet; show it as \"no deliveries yet\", not as 0."
                                                                }
                                                            }
                                                        },
                                                        "last_delivered_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When a delivery to this webhook last succeeded, in ISO 8601 UTC. Null when none has succeeded yet; check `deliveries` to see whether any were tried."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/contacts": {
            "get": {
                "operationId": "getContacts",
                "summary": "List contacts",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "since_last_changed",
                        "in": "query",
                        "required": false,
                        "description": "ISO 8601. Returns only contacts modified strictly after this moment. URL-encode it.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "state",
                        "in": "query",
                        "required": false,
                        "description": "One of `subscribed`, `unsubscribed`, `bounced`, `complained`, `suppressed`. What the product will do, suppression list included.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "The stored row value. Kept because it is published; prefer `state`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Matches email or name.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "list_id",
                        "in": "query",
                        "required": false,
                        "description": "Only contacts on this list.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "field",
                        "in": "query",
                        "required": false,
                        "description": "Filter by one custom field, by its key from `GET /contact-fields`, like `country`. Use with `field_op` and `field_value`: `?field=country&field_value=nigeria`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "field_op",
                        "in": "query",
                        "required": false,
                        "description": "How `field` is matched: `contains` (the default), `equals`, `is_set` (has any value) or `is_not_set` (empty). Case does not matter, the same as in a segment.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "field_value",
                        "in": "query",
                        "required": false,
                        "description": "What `field` is compared with. Not needed for `is_set` and `is_not_set`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "required": false,
                        "description": "Only contacts carrying this tag, matched by NAME and case-insensitively \u2014 tags are written by name everywhere, never by id.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "interest_id",
                        "in": "query",
                        "required": false,
                        "description": "Only contacts who chose this interest, matched by ID. An interest's name is form copy; rewording it must not change who matches.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "email_status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by address check: one value or a comma list of `valid`, `risky`, `invalid`, `unknown`, `pending`, `not_checked` and `never_checked`. `never_checked` means from before Bounce protection launched; for everything not checked yet, use `not_checked,never_checked`. `inbox_full` selects contacts on a full-inbox hold (they also read `risky`).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "created_via",
                        "in": "query",
                        "required": false,
                        "description": "Filter by how the contact was added: one value or a comma list of `dashboard`, `api` (POST /contacts), `upsert` (PUT /contacts), `import` and `event`. `api,upsert` means added by your app.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Page size.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "contact"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Unique identifier for the contact."
                                                                    },
                                                                    "email": {
                                                                        "type": "string",
                                                                        "format": "email",
                                                                        "description": "Lower-cased and trimmed on write, so the address you read back may not be byte-identical to the one you sent."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The contact's name. Null when none was given; `{{ name }}` is then empty unless your template gives a fallback."
                                                                    },
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "subscribed",
                                                                            "unsubscribed",
                                                                            "bounced",
                                                                            "complained",
                                                                            "suppressed"
                                                                        ],
                                                                        "description": "Whether this contact will be emailed. `subscribed` means yes; any other value is the reason not. It combines the contact's `status` with your suppression list, so a subscribed contact whose address is suppressed reads `suppressed`. Read-only: you set `status` (`subscribed`, `unsubscribed`, `bounced` or `complained`) instead. Note that `?status=` filters on `status`, not on this."
                                                                    },
                                                                    "email_status": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "pending",
                                                                            "valid",
                                                                            "risky",
                                                                            "invalid",
                                                                            "unknown",
                                                                            "not_checked"
                                                                        ],
                                                                        "description": "The result of checking whether the mailbox exists. `valid`: it exists. `invalid`: it does not. `risky`: it may not take mail (a catch-all domain, a role address such as info@, a throwaway address or a full inbox). `unknown`: the check could not tell. `pending`: being checked. `not_checked`: added after Bounce protection launched and not checked. Null: never checked, from before Bounce protection launched. Read-only; filter with `?email_status=`."
                                                                    },
                                                                    "email_full_until": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "Until when marketing to this contact is held because their inbox is full. When a check finds the inbox full, marketing waits 7 days; near the end it is checked again for free and the hold either ends or runs another 7 days. App email is never held. Null means no hold. Read-only."
                                                                    },
                                                                    "fields": {
                                                                        "type": "object",
                                                                        "additionalProperties": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "Custom field values, keyed by the field's `key` (the name `{{ signup_date }}` uses). Always an object, `{}` when empty. Values are strings as stored; field defaults are not filled in here. When writing, send these as `attributes`."
                                                                    },
                                                                    "lists": {
                                                                        "type": "array",
                                                                        "nullable": true,
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "id": {
                                                                                    "type": "string"
                                                                                },
                                                                                "name": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        },
                                                                        "description": "The lists this contact is on, with their names. When writing, send list IDs as `list_ids`."
                                                                    },
                                                                    "tags": {
                                                                        "type": "array",
                                                                        "nullable": true,
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "id": {
                                                                                    "type": "string"
                                                                                },
                                                                                "name": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        },
                                                                        "description": "Your labels on this contact, with their names."
                                                                    },
                                                                    "interests": {
                                                                        "type": "array",
                                                                        "nullable": true,
                                                                        "description": "What this contact chose on a form, each with the question it answers. `[]` means they chose nothing.",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "id": {
                                                                                    "type": "string",
                                                                                    "description": "Match on this in a segment rule, never on the name."
                                                                                },
                                                                                "name": {
                                                                                    "type": "string",
                                                                                    "description": "The answer, as the contact read it."
                                                                                },
                                                                                "category_id": {
                                                                                    "type": "string",
                                                                                    "description": "The question this answers."
                                                                                },
                                                                                "category_title": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "description": "The question in words. `null` MEANS NOT INCLUDED \u2014 the category was not loaded, never that the question has no title."
                                                                                }
                                                                            }
                                                                        }
                                                                    },
                                                                    "consent": {
                                                                        "type": "object",
                                                                        "description": "How this contact agreed to be emailed. Each field is null when we have no record. Set it when you import from another service, so your proof of consent comes with your contacts.",
                                                                        "properties": {
                                                                            "at": {
                                                                                "type": "string",
                                                                                "format": "date-time",
                                                                                "nullable": true,
                                                                                "description": "When they agreed. Null when unknown."
                                                                            },
                                                                            "ip": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The IP address they agreed from. Null when unknown."
                                                                            },
                                                                            "source": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "Where they agreed, such as a form name, a URL or \"imported from Mailchimp\". Null when unknown."
                                                                            }
                                                                        }
                                                                    },
                                                                    "source": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "How this contact was added: `manual`, `import_api`, `import_csv` or your own text (up to 50 characters). Null when nothing was recorded."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Your contacts, newest first.\n\n**For a sync, use `since_last_changed`.** It answers the only question an integration\nkeeping its own copy actually has \u2014 what moved \u2014 and turns a nightly full-list crawl into a\nrequest that usually returns nothing. The value is an ISO 8601 timestamp; remember to\nURL-encode it, because the `+` in `+00:00` means a space in a query string.\n\nA `since_last_changed` we cannot parse is IGNORED and you get everything, rather than\nnothing. The two failures are not symmetrical: a sync handed zero rows concludes it is up to\ndate and stops, and silently misses every change from then on.\n\n**Filter on `state`, not `status`.** `status` is what the contact row says; `state` is what\nthe product will actually do, and reconciles that row against your organization's\nsuppression list. A contact whose row says `subscribed` but whose address you suppressed\nanswers `state: \"suppressed\"` and will never be mailed, even though `?status=subscribed`\nreturns it."
            },
            "post": {
                "operationId": "postContacts",
                "summary": "Create a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the contact."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "Lower-cased and trimmed on write, so the address you read back may not be byte-identical to the one you sent."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The contact's name. Null when none was given; `{{ name }}` is then empty unless your template gives a fallback."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "subscribed",
                                                                "unsubscribed",
                                                                "bounced",
                                                                "complained",
                                                                "suppressed"
                                                            ],
                                                            "description": "Whether this contact will be emailed. `subscribed` means yes; any other value is the reason not. It combines the contact's `status` with your suppression list, so a subscribed contact whose address is suppressed reads `suppressed`. Read-only: you set `status` (`subscribed`, `unsubscribed`, `bounced` or `complained`) instead. Note that `?status=` filters on `status`, not on this."
                                                        },
                                                        "email_status": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "pending",
                                                                "valid",
                                                                "risky",
                                                                "invalid",
                                                                "unknown",
                                                                "not_checked"
                                                            ],
                                                            "description": "The result of checking whether the mailbox exists. `valid`: it exists. `invalid`: it does not. `risky`: it may not take mail (a catch-all domain, a role address such as info@, a throwaway address or a full inbox). `unknown`: the check could not tell. `pending`: being checked. `not_checked`: added after Bounce protection launched and not checked. Null: never checked, from before Bounce protection launched. Read-only; filter with `?email_status=`."
                                                        },
                                                        "email_full_until": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "Until when marketing to this contact is held because their inbox is full. When a check finds the inbox full, marketing waits 7 days; near the end it is checked again for free and the hold either ends or runs another 7 days. App email is never held. Null means no hold. Read-only."
                                                        },
                                                        "fields": {
                                                            "type": "object",
                                                            "additionalProperties": {
                                                                "type": "string"
                                                            },
                                                            "description": "Custom field values, keyed by the field's `key` (the name `{{ signup_date }}` uses). Always an object, `{}` when empty. Values are strings as stored; field defaults are not filled in here. When writing, send these as `attributes`."
                                                        },
                                                        "lists": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "The lists this contact is on, with their names. When writing, send list IDs as `list_ids`."
                                                        },
                                                        "tags": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "Your labels on this contact, with their names."
                                                        },
                                                        "interests": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "description": "What this contact chose on a form, each with the question it answers. `[]` means they chose nothing.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Match on this in a segment rule, never on the name."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The answer, as the contact read it."
                                                                    },
                                                                    "category_id": {
                                                                        "type": "string",
                                                                        "description": "The question this answers."
                                                                    },
                                                                    "category_title": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The question in words. `null` MEANS NOT INCLUDED \u2014 the category was not loaded, never that the question has no title."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "consent": {
                                                            "type": "object",
                                                            "description": "How this contact agreed to be emailed. Each field is null when we have no record. Set it when you import from another service, so your proof of consent comes with your contacts.",
                                                            "properties": {
                                                                "at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When they agreed. Null when unknown."
                                                                },
                                                                "ip": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The IP address they agreed from. Null when unknown."
                                                                },
                                                                "source": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Where they agreed, such as a form name, a URL or \"imported from Mailchimp\". Null when unknown."
                                                                }
                                                            }
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "How this contact was added: `manual`, `import_api`, `import_csv` or your own text (up to 50 characters). Null when nothing was recorded."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        },
                        "headers": {
                            "X-Mailyte-Checks-Remaining": {
                                "description": "The checks your account has left after this request: this month's plan checks, then bought checks, then send credits bought before checks launched, all counted in checks. Sent only once Bounce protection is on for your account.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "X-Mailyte-Checks-Warning": {
                                "description": "`running_low`: at your pace of the last 7 days the checks last under a week, or 80% of this month's plan checks are used and you have none bought. `ran_out`: no checks are left and a new contact this month could not be checked, so it was added as `not_checked`. Absent when neither applies, and until Bounce protection is on for your account.",
                                "schema": {
                                    "type": "string",
                                    "enum": [
                                        "running_low",
                                        "ran_out"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "**Checks.** Once Bounce protection is on for your account, a new contact, or a contact whose address\nchanges, is checked in the background with one check: its `email_status` reads `pending` until the\nanswer lands, then `valid`, `risky`, `invalid` (and the contact becomes `bounced`) or `unknown`. With\nBounce protection switched off, or no checks left, the contact is still saved, as `not_checked`. A\ncontact from an event (`unconfirmed`) is checked when it becomes `subscribed`. The write never fails\nbecause of a check.\n\nSend `\"check\": \"wait\"` to have the address checked before we answer (up to about 8 seconds), so the\n`email_status` in the reply is already the answer. Any other value is ignored. If the checker is\nslow, the contact is saved and checked in the background; if no checks are left, it is saved as\n`not_checked`.\n\nThe reply carries `X-Mailyte-Checks-Remaining` and, when it applies, `X-Mailyte-Checks-Warning:\nrunning_low | ran_out`. Neither is sent until Bounce protection is on for your account.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Their email address. If it is already one of your contacts, nothing about them changes: they are only added to `list_ids`.",
                                        "example": "ada@example.com"
                                    },
                                    "name": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The person's name, as it should appear in your emails (`{{name}}`).",
                                        "example": "Ada Obi",
                                        "x-example": "Spring newsletter"
                                    },
                                    "attributes": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "Custom fields as key\u2013value pairs, for example `{\"city\": \"Lagos\", \"plan\": \"pro\"}`. Use the keys from `GET /contact-fields`.",
                                        "x-example": {
                                            "city": "Lagos"
                                        }
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "subscribed",
                                            "unsubscribed",
                                            "bounced",
                                            "complained"
                                        ],
                                        "description": "Defaults to `subscribed`. Bring someone over as `unsubscribed`, `bounced` or `complained` and they are never emailed by mistake."
                                    },
                                    "source": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 50,
                                        "description": "Optional. Where this contact came from, in your own words (up to 50 characters), like `checkout`.",
                                        "x-example": "checkout"
                                    },
                                    "consented_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "When this person agreed to be emailed, in ISO 8601. Bring it when you move from another service: it is your proof of consent.",
                                        "x-example": "2026-03-14T10:22:00Z"
                                    },
                                    "consent_ip": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 45,
                                        "description": "The IP address the agreement came from. IPv4 or IPv6.",
                                        "x-example": "203.0.113.10"
                                    },
                                    "consent_source": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Where they agreed, in your own words: a form name, a checkout step, \"imported from Mailchimp\".",
                                        "x-example": "Website footer form"
                                    },
                                    "list_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Lists to put the contact on. Copy IDs from Contacts \u2192 Lists in the dashboard, or read them from `GET /contact-lists`.",
                                        "example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ],
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "check": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Send `\"wait\"` to have the address checked before we answer (up to about 8 seconds), so `email_status` in the reply is already the result. Any other value is ignored.",
                                        "x-example": "wait"
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            },
                            "example": {
                                "email": "ada@example.com",
                                "name": "Ada Obi",
                                "list_ids": [
                                    "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "put": {
                "operationId": "putContacts",
                "summary": "Create or update a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "201 when the contact was created, 200 when it already existed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the contact."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "Lower-cased and trimmed on write, so the address you read back may not be byte-identical to the one you sent."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The contact's name. Null when none was given; `{{ name }}` is then empty unless your template gives a fallback."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "subscribed",
                                                                "unsubscribed",
                                                                "bounced",
                                                                "complained",
                                                                "suppressed"
                                                            ],
                                                            "description": "Whether this contact will be emailed. `subscribed` means yes; any other value is the reason not. It combines the contact's `status` with your suppression list, so a subscribed contact whose address is suppressed reads `suppressed`. Read-only: you set `status` (`subscribed`, `unsubscribed`, `bounced` or `complained`) instead. Note that `?status=` filters on `status`, not on this."
                                                        },
                                                        "email_status": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "pending",
                                                                "valid",
                                                                "risky",
                                                                "invalid",
                                                                "unknown",
                                                                "not_checked"
                                                            ],
                                                            "description": "The result of checking whether the mailbox exists. `valid`: it exists. `invalid`: it does not. `risky`: it may not take mail (a catch-all domain, a role address such as info@, a throwaway address or a full inbox). `unknown`: the check could not tell. `pending`: being checked. `not_checked`: added after Bounce protection launched and not checked. Null: never checked, from before Bounce protection launched. Read-only; filter with `?email_status=`."
                                                        },
                                                        "email_full_until": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "Until when marketing to this contact is held because their inbox is full. When a check finds the inbox full, marketing waits 7 days; near the end it is checked again for free and the hold either ends or runs another 7 days. App email is never held. Null means no hold. Read-only."
                                                        },
                                                        "fields": {
                                                            "type": "object",
                                                            "additionalProperties": {
                                                                "type": "string"
                                                            },
                                                            "description": "Custom field values, keyed by the field's `key` (the name `{{ signup_date }}` uses). Always an object, `{}` when empty. Values are strings as stored; field defaults are not filled in here. When writing, send these as `attributes`."
                                                        },
                                                        "lists": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "The lists this contact is on, with their names. When writing, send list IDs as `list_ids`."
                                                        },
                                                        "tags": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "Your labels on this contact, with their names."
                                                        },
                                                        "interests": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "description": "What this contact chose on a form, each with the question it answers. `[]` means they chose nothing.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Match on this in a segment rule, never on the name."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The answer, as the contact read it."
                                                                    },
                                                                    "category_id": {
                                                                        "type": "string",
                                                                        "description": "The question this answers."
                                                                    },
                                                                    "category_title": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The question in words. `null` MEANS NOT INCLUDED \u2014 the category was not loaded, never that the question has no title."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "consent": {
                                                            "type": "object",
                                                            "description": "How this contact agreed to be emailed. Each field is null when we have no record. Set it when you import from another service, so your proof of consent comes with your contacts.",
                                                            "properties": {
                                                                "at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When they agreed. Null when unknown."
                                                                },
                                                                "ip": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The IP address they agreed from. Null when unknown."
                                                                },
                                                                "source": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Where they agreed, such as a form name, a URL or \"imported from Mailchimp\". Null when unknown."
                                                                }
                                                            }
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "How this contact was added: `manual`, `import_api`, `import_csv` or your own text (up to 50 characters). Null when nothing was recorded."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        },
                        "headers": {
                            "X-Mailyte-Checks-Remaining": {
                                "description": "The checks your account has left after this request: this month's plan checks, then bought checks, then send credits bought before checks launched, all counted in checks. Sent only once Bounce protection is on for your account.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "X-Mailyte-Checks-Warning": {
                                "description": "`running_low`: at your pace of the last 7 days the checks last under a week, or 80% of this month's plan checks are used and you have none bought. `ran_out`: no checks are left and a new contact this month could not be checked, so it was added as `not_checked`. Absent when neither applies, and until Bounce protection is on for your account.",
                                "schema": {
                                    "type": "string",
                                    "enum": [
                                        "running_low",
                                        "ran_out"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Creates the contact if this email is new, updates it if it is not \u2014 the call to reach for\nwhen you are keeping your own database in step with ours.\n\nWithout it a sync needs a GET, a branch, and then a POST or a PATCH: three round trips, and\na race between the read and the write.\n\n**`status_if_new` is the one to understand.** It applies only when the contact is created.\nA nightly sync that sends `status: subscribed` for everybody in your CRM would resurrect\nevery unsubscribe it touched \u2014 the worst thing this API can do to you, because the person\nasked not to be mailed and then was. Send `status_if_new` to say \"subscribed as far as I\nknow\" without overriding what the contact themselves decided here; send `status` only when\nyou mean to change it.\n\nLists named in `list_ids` are added. The contact's other memberships are left alone.\n\n**Checks.** Once Bounce protection is on for your account, a new contact, or a contact whose address\nchanges, is checked in the background with one check: its `email_status` reads `pending` until the\nanswer lands, then `valid`, `risky`, `invalid` (and the contact becomes `bounced`) or `unknown`. With\nBounce protection switched off, or no checks left, the contact is still saved, as `not_checked`. A\ncontact from an event (`unconfirmed`) is checked when it becomes `subscribed`. The write never fails\nbecause of a check.\n\nSend `\"check\": \"wait\"` to have the address checked before we answer (up to about 8 seconds), so the\n`email_status` in the reply is already the answer. Any other value is ignored. If the checker is\nslow, the contact is saved and checked in the background; if no checks are left, it is saved as\n`not_checked`.\n\nThe reply carries `X-Mailyte-Checks-Remaining` and, when it applies, `X-Mailyte-Checks-Warning:\nrunning_low | ran_out`. Neither is sent until Bounce protection is on for your account.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "The key. Matched case-insensitively."
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "The person's name, as it should appear in your emails (`{{name}}`).",
                                        "example": "Ada Obi",
                                        "x-example": "Spring newsletter"
                                    },
                                    "attributes": {
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "Custom fields as key\u2013value pairs. On a contact you already have, this REPLACES all their custom fields: send every field you want to keep.",
                                        "x-example": {
                                            "city": "Lagos"
                                        }
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "subscribed",
                                            "unsubscribed",
                                            "bounced",
                                            "complained"
                                        ],
                                        "description": "Applied whether the contact is new or existing. Use it only when you mean to change somebody\u2019s state."
                                    },
                                    "status_if_new": {
                                        "type": "string",
                                        "enum": [
                                            "subscribed",
                                            "unsubscribed",
                                            "bounced",
                                            "complained"
                                        ],
                                        "description": "Applied ONLY on create, and ignored for a contact that already exists. This is what makes a repeated sync safe."
                                    },
                                    "source": {
                                        "type": "string",
                                        "description": "Optional. Where this contact came from, in your own words (up to 50 characters), like `checkout`.",
                                        "x-example": "checkout"
                                    },
                                    "list_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Lists to add the contact to. Their other lists are left alone. Copy IDs from Contacts \u2192 Lists, or read them from `GET /contact-lists`.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "consented_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "When this person agreed to be emailed, in ISO 8601. Bring it when you move from another service: it is your proof of consent.",
                                        "x-example": "2026-03-14T10:22:00Z"
                                    },
                                    "consent_ip": {
                                        "type": "string",
                                        "description": "The address the agreement came from. IPv4 or IPv6.",
                                        "x-example": "203.0.113.10"
                                    },
                                    "consent_source": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Where it happened, in your own words \u2014 a form name, a checkout step, \"imported from Mailchimp\". Free text, because what counts as evidence differs by regulator and we will not pick for you.",
                                        "x-example": "Website footer form"
                                    },
                                    "check": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "Send `\"wait\"` to check the address before we answer (up to about 8 seconds) when this creates the contact or changes its address, while Bounce protection is on. Any other value is ignored.",
                                        "x-example": "wait"
                                    }
                                }
                            },
                            "example": {
                                "email": "ada@example.com",
                                "name": "Ada Lovelace",
                                "status_if_new": "subscribed",
                                "attributes": {
                                    "plan": "pro"
                                },
                                "check": "wait"
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/contacts/import": {
            "post": {
                "operationId": "postContactsImport",
                "summary": "Import contacts",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The counters always sum: `imported + skipped_invalid + skipped_duplicate + skipped_over_plan == total`.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_import"
                                                            ]
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Rows we were given. For a CSV this is DATA rows \u2014 a recognised header row is not counted."
                                                        },
                                                        "imported": {
                                                            "type": "integer",
                                                            "description": "Rows that became new contacts."
                                                        },
                                                        "skipped_invalid": {
                                                            "type": "integer",
                                                            "description": "Rows skipped because the address was missing or invalid, or a required field was empty. Other rows still import."
                                                        },
                                                        "skipped_duplicate": {
                                                            "type": "integer",
                                                            "description": "Addresses you already have, plus repeats in the file. Existing contacts are left as they are, so re-importing never re-subscribes anyone who unsubscribed."
                                                        },
                                                        "skipped_over_plan": {
                                                            "type": "integer",
                                                            "description": "Rows past the subscribed contacts your Marketing plan holds. The rows that fit are imported; `plan_limit` names the plan that takes the rest."
                                                        },
                                                        "error_count": {
                                                            "type": "integer",
                                                            "description": "How many rows failed in total. Equal to `skipped_invalid + skipped_duplicate + skipped_over_plan`, and the number to trust \u2014 `errors` below is capped, so a file where everything failed reports 4,000 here and lists 100."
                                                        },
                                                        "errors": {
                                                            "type": "array",
                                                            "description": "The rows that failed, in file order, up to 100. `error_count` gives the full number. `[]` means every row was accepted.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "row": {
                                                                        "type": "integer",
                                                                        "description": "1-based, counting DATA rows, so it lines up with your spreadsheet after the header."
                                                                    },
                                                                    "email": {
                                                                        "type": "string",
                                                                        "description": "The address exactly as you sent it, before normalising \u2014 empty when the row had none."
                                                                    },
                                                                    "reason": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "missing_email",
                                                                            "invalid_email",
                                                                            "duplicate_in_file",
                                                                            "already_exists",
                                                                            "missing_required_field",
                                                                            "over_plan"
                                                                        ],
                                                                        "description": "Why the row failed. `duplicate_in_file`: the address appears twice in your file. `already_exists`: you already have this contact. `missing_required_field`: a required contact field is empty, and `message` names it."
                                                                    },
                                                                    "message": {
                                                                        "type": "string",
                                                                        "description": "The same thing in words, safe to show a person. For a duplicate it names the earlier row."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "plan_limit": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Null unless rows were stopped by your plan. Then the same context a 402 carries: `limit_type`, `limit`, `current`, `suggested_product`, `cta_label` and `upgrade_url`."
                                                        },
                                                        "list": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The list named by `list_id`, with how many of the file's contacts joined it (new ones and ones you already had). Null when no list was given.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "added": {
                                                                    "type": "integer"
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        },
                        "headers": {
                            "X-Mailyte-Checks-Remaining": {
                                "description": "The checks your account has left after this request: this month's plan checks, then bought checks, then send credits bought before checks launched, all counted in checks. Sent only once Bounce protection is on for your account.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "X-Mailyte-Checks-Warning": {
                                "description": "`running_low`: at your pace of the last 7 days the checks last under a week, or 80% of this month's plan checks are used and you have none bought. `ran_out`: no checks are left and a new contact this month could not be checked, so it was added as `not_checked`. Absent when neither applies, and until Bounce protection is on for your account.",
                                "schema": {
                                    "type": "string",
                                    "enum": [
                                        "running_low",
                                        "ran_out"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Add up to 10,000 contacts in one request, each with a name and any custom fields. New\ncontacts are added as `subscribed`. An address that is already a contact is left exactly as\nit is (name, fields and status) and counted in `skipped_duplicate`: import never updates\nanyone, so it can never re-subscribe somebody who unsubscribed. To update people, use\n`PUT /contacts`.\n\nA bad row never fails the request. A row with no address, an invalid address, or no value\nfor a custom field your account marks required is skipped, and the reply's `errors` names\nit by row number. Everything else is imported.\n\n**Two ways to send contacts.** Send JSON with a `contacts` array, as in the example below.\nOr upload a CSV file as a form (`multipart/form-data`) in a field called `file`:\n\n```bash\ncurl -X POST 'https://app.mailyte.com/api/v1/contacts/import' \\\n  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \\\n  -F 'file=@contacts.csv' \\\n  -F 'list_id=01JBT8XQ2M9WYC3K4F6R7S8T9V'\n```\n\nThe file's first row should be a header with an `email` column and, optionally, a `name`\ncolumn. Every other column becomes a custom field named after its header (\"Signup Date\"\nbecomes `signup_date`). Without a header, the first column is read as the email and the\nsecond as the name. Send `file` or `contacts`, not both.\n\n**Checks.** Once Bounce protection is on for your account, each new address uses one\ncheck and is checked in the background: `email_status` reads `pending` until the answer\nlands, then `valid`, `risky`, `invalid` or `unknown`. Read it with `GET /contacts/{id}`, or\nsubscribe to the `contact.checked` webhook. If your checks run short, as many new contacts\nas there are checks for are checked and the rest are added as `not_checked`. With Bounce\nprotection switched off they are added as `not_checked`. Until then an import's addresses\nare checked free, as before.\n\nThe reply carries `X-Mailyte-Checks-Remaining` and, when it applies,\n`X-Mailyte-Checks-Warning: running_low | ran_out`, once Bounce protection is on.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "contacts"
                                ],
                                "properties": {
                                    "contacts": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 10000,
                                        "description": "The contacts to add, 1 to 10,000 per request.",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "email"
                                            ],
                                            "properties": {
                                                "email": {
                                                    "type": "string",
                                                    "format": "email",
                                                    "description": "Their email address. Case does not matter: `Ada@Example.com` and `ada@example.com` are the same contact."
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "description": "Their name, as it should appear in your emails.",
                                                    "x-example": "Spring newsletter"
                                                },
                                                "attributes": {
                                                    "type": "object",
                                                    "additionalProperties": true,
                                                    "description": "Custom fields as key\u2013value pairs, for example `{\"city\": \"Lagos\", \"plan\": \"pro\"}`. Use the keys from `GET /contact-fields`; a key your account has not seen before is kept too.",
                                                    "x-example": {
                                                        "city": "Lagos"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "list_id": {
                                        "type": "string",
                                        "description": "Optional. The ID of a list to put every address in this request on, new contacts and ones you already had. Copy it from Contacts \u2192 Lists in the dashboard, or read it from `GET /contact-lists`."
                                    }
                                }
                            },
                            "example": {
                                "list_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                "contacts": [
                                    {
                                        "email": "ada@example.com",
                                        "name": "Ada Obi"
                                    },
                                    {
                                        "email": "tunde@example.com",
                                        "name": "Tunde Bello",
                                        "attributes": {
                                            "city": "Lagos",
                                            "plan": "pro"
                                        }
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/contacts/attribute-keys": {
            "get": {
                "operationId": "getContactsAttributeKeys",
                "summary": "Attribute Keys (contact)",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "description": "One usable key of a contact's `fields` object. Serves both `GET /contact-fields` (the declared catalog) and `GET /contacts/attribute-keys` (the catalog plus keys observed on contact data), which is why `declared` exists.",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "contact_field"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "The definition's id, for `PUT`/`DELETE /contact-fields/{field}`. `null` when `declared` is false \u2014 there is no definition row, so there is nothing to address."
                                                            },
                                                            "key": {
                                                                "type": "string",
                                                                "description": "The stable name. This is the key inside a contact's `fields` object and the `{{ signup_date }}` tag in campaign content. Contact values are keyed by this, never by `id`."
                                                            },
                                                            "declared": {
                                                                "type": "boolean",
                                                                "description": "Whether this key is defined as a contact field (with a label, type and default), or was only seen on contact data. Both can be used in content and segment rules."
                                                            },
                                                            "label": {
                                                                "type": "string",
                                                                "description": "Display name. Derived from the key for an undeclared one."
                                                            },
                                                            "type": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "text",
                                                                    "number",
                                                                    "date",
                                                                    "boolean"
                                                                ],
                                                                "description": "How a value should be EDITED and displayed. Not a storage type: every value in a contact's `fields` object is a string whatever this says, and nothing is coerced."
                                                            },
                                                            "required": {
                                                                "type": "boolean",
                                                                "description": "Whether every contact must have a value. Checked when a contact is created, and when an update would clear the value; existing contacts are not checked. A default value does not count. Always false for a key that is not defined."
                                                            },
                                                            "default_value": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "Substituted at send time for contacts with no value of their own. It is never written into a contact's `fields`."
                                                            },
                                                            "help_text": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "The hint shown beside this field on a form. `null` MEANS NONE WAS WRITTEN \u2014 it carries no behaviour, so an absent hint changes nothing about what the field accepts."
                                                            },
                                                            "contacts_with_value": {
                                                                "type": "integer",
                                                                "description": "How many contacts carry a non-empty value for this key \u2014 the \"is it safe to delete this\" signal. Always an integer."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true,
                                                                "description": "`null` when `declared` is false: an observed key has no definition row and therefore no creation time. Genuinely unknown, not zero."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/contacts/{contact}": {
            "get": {
                "operationId": "getContactsContact",
                "summary": "Retrieve a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the contact."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "Lower-cased and trimmed on write, so the address you read back may not be byte-identical to the one you sent."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The contact's name. Null when none was given; `{{ name }}` is then empty unless your template gives a fallback."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "subscribed",
                                                                "unsubscribed",
                                                                "bounced",
                                                                "complained",
                                                                "suppressed"
                                                            ],
                                                            "description": "Whether this contact will be emailed. `subscribed` means yes; any other value is the reason not. It combines the contact's `status` with your suppression list, so a subscribed contact whose address is suppressed reads `suppressed`. Read-only: you set `status` (`subscribed`, `unsubscribed`, `bounced` or `complained`) instead. Note that `?status=` filters on `status`, not on this."
                                                        },
                                                        "email_status": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "pending",
                                                                "valid",
                                                                "risky",
                                                                "invalid",
                                                                "unknown",
                                                                "not_checked"
                                                            ],
                                                            "description": "The result of checking whether the mailbox exists. `valid`: it exists. `invalid`: it does not. `risky`: it may not take mail (a catch-all domain, a role address such as info@, a throwaway address or a full inbox). `unknown`: the check could not tell. `pending`: being checked. `not_checked`: added after Bounce protection launched and not checked. Null: never checked, from before Bounce protection launched. Read-only; filter with `?email_status=`."
                                                        },
                                                        "email_full_until": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "Until when marketing to this contact is held because their inbox is full. When a check finds the inbox full, marketing waits 7 days; near the end it is checked again for free and the hold either ends or runs another 7 days. App email is never held. Null means no hold. Read-only."
                                                        },
                                                        "fields": {
                                                            "type": "object",
                                                            "additionalProperties": {
                                                                "type": "string"
                                                            },
                                                            "description": "Custom field values, keyed by the field's `key` (the name `{{ signup_date }}` uses). Always an object, `{}` when empty. Values are strings as stored; field defaults are not filled in here. When writing, send these as `attributes`."
                                                        },
                                                        "lists": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "The lists this contact is on, with their names. When writing, send list IDs as `list_ids`."
                                                        },
                                                        "tags": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "Your labels on this contact, with their names."
                                                        },
                                                        "interests": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "description": "What this contact chose on a form, each with the question it answers. `[]` means they chose nothing.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Match on this in a segment rule, never on the name."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The answer, as the contact read it."
                                                                    },
                                                                    "category_id": {
                                                                        "type": "string",
                                                                        "description": "The question this answers."
                                                                    },
                                                                    "category_title": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The question in words. `null` MEANS NOT INCLUDED \u2014 the category was not loaded, never that the question has no title."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "consent": {
                                                            "type": "object",
                                                            "description": "How this contact agreed to be emailed. Each field is null when we have no record. Set it when you import from another service, so your proof of consent comes with your contacts.",
                                                            "properties": {
                                                                "at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When they agreed. Null when unknown."
                                                                },
                                                                "ip": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The IP address they agreed from. Null when unknown."
                                                                },
                                                                "source": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Where they agreed, such as a form name, a URL or \"imported from Mailchimp\". Null when unknown."
                                                                }
                                                            }
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "How this contact was added: `manual`, `import_api`, `import_csv` or your own text (up to 50 characters). Null when nothing was recorded."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putContactsContact",
                "summary": "Update a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the contact."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "Lower-cased and trimmed on write, so the address you read back may not be byte-identical to the one you sent."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The contact's name. Null when none was given; `{{ name }}` is then empty unless your template gives a fallback."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "subscribed",
                                                                "unsubscribed",
                                                                "bounced",
                                                                "complained",
                                                                "suppressed"
                                                            ],
                                                            "description": "Whether this contact will be emailed. `subscribed` means yes; any other value is the reason not. It combines the contact's `status` with your suppression list, so a subscribed contact whose address is suppressed reads `suppressed`. Read-only: you set `status` (`subscribed`, `unsubscribed`, `bounced` or `complained`) instead. Note that `?status=` filters on `status`, not on this."
                                                        },
                                                        "email_status": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "pending",
                                                                "valid",
                                                                "risky",
                                                                "invalid",
                                                                "unknown",
                                                                "not_checked"
                                                            ],
                                                            "description": "The result of checking whether the mailbox exists. `valid`: it exists. `invalid`: it does not. `risky`: it may not take mail (a catch-all domain, a role address such as info@, a throwaway address or a full inbox). `unknown`: the check could not tell. `pending`: being checked. `not_checked`: added after Bounce protection launched and not checked. Null: never checked, from before Bounce protection launched. Read-only; filter with `?email_status=`."
                                                        },
                                                        "email_full_until": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "Until when marketing to this contact is held because their inbox is full. When a check finds the inbox full, marketing waits 7 days; near the end it is checked again for free and the hold either ends or runs another 7 days. App email is never held. Null means no hold. Read-only."
                                                        },
                                                        "fields": {
                                                            "type": "object",
                                                            "additionalProperties": {
                                                                "type": "string"
                                                            },
                                                            "description": "Custom field values, keyed by the field's `key` (the name `{{ signup_date }}` uses). Always an object, `{}` when empty. Values are strings as stored; field defaults are not filled in here. When writing, send these as `attributes`."
                                                        },
                                                        "lists": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "The lists this contact is on, with their names. When writing, send list IDs as `list_ids`."
                                                        },
                                                        "tags": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "Your labels on this contact, with their names."
                                                        },
                                                        "interests": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "description": "What this contact chose on a form, each with the question it answers. `[]` means they chose nothing.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Match on this in a segment rule, never on the name."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The answer, as the contact read it."
                                                                    },
                                                                    "category_id": {
                                                                        "type": "string",
                                                                        "description": "The question this answers."
                                                                    },
                                                                    "category_title": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The question in words. `null` MEANS NOT INCLUDED \u2014 the category was not loaded, never that the question has no title."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "consent": {
                                                            "type": "object",
                                                            "description": "How this contact agreed to be emailed. Each field is null when we have no record. Set it when you import from another service, so your proof of consent comes with your contacts.",
                                                            "properties": {
                                                                "at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When they agreed. Null when unknown."
                                                                },
                                                                "ip": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The IP address they agreed from. Null when unknown."
                                                                },
                                                                "source": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Where they agreed, such as a form name, a URL or \"imported from Mailchimp\". Null when unknown."
                                                                }
                                                            }
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "How this contact was added: `manual`, `import_api`, `import_csv` or your own text (up to 50 characters). Null when nothing was recorded."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        },
                        "headers": {
                            "X-Mailyte-Checks-Remaining": {
                                "description": "The checks your account has left after this request: this month's plan checks, then bought checks, then send credits bought before checks launched, all counted in checks. Sent only once Bounce protection is on for your account.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "X-Mailyte-Checks-Warning": {
                                "description": "`running_low`: at your pace of the last 7 days the checks last under a week, or 80% of this month's plan checks are used and you have none bought. `ran_out`: no checks are left and a new contact this month could not be checked, so it was added as `not_checked`. Absent when neither applies, and until Bounce protection is on for your account.",
                                "schema": {
                                    "type": "string",
                                    "enum": [
                                        "running_low",
                                        "ran_out"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Change a contact's details. Send only the fields you want to change.\n\n**Lists are not changed here.** To add someone to a list use `POST /contact-lists/{id}/members`, or `PUT /contacts` with `list_ids`.\n\n**Checks.** Once Bounce protection is on for your account, a new contact, or a contact whose address\nchanges, is checked in the background with one check: its `email_status` reads `pending` until the\nanswer lands, then `valid`, `risky`, `invalid` (and the contact becomes `bounced`) or `unknown`. With\nBounce protection switched off, or no checks left, the contact is still saved, as `not_checked`. A\ncontact from an event (`unconfirmed`) is checked when it becomes `subscribed`. The write never fails\nbecause of a check.\n\nSend `\"check\": \"wait\"` to have the address checked before we answer (up to about 8 seconds), so the\n`email_status` in the reply is already the answer. Any other value is ignored. If the checker is\nslow, the contact is saved and checked in the background; if no checks are left, it is saved as\n`not_checked`.\n\nThe reply carries `X-Mailyte-Checks-Remaining` and, when it applies, `X-Mailyte-Checks-Warning:\nrunning_low | ran_out`. Neither is sent until Bounce protection is on for your account.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The person's name, as it should appear in your emails (`{{name}}`).",
                                        "example": "Ada Obi",
                                        "x-example": "Spring newsletter"
                                    },
                                    "attributes": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "Custom fields as key\u2013value pairs. This REPLACES all of the contact's custom fields: send every field you want to keep.",
                                        "example": {
                                            "city": "Abuja"
                                        },
                                        "x-example": {
                                            "city": "Lagos"
                                        }
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "subscribed",
                                            "unsubscribed",
                                            "bounced",
                                            "complained"
                                        ],
                                        "description": "Change their status. Set `subscribed` again only when the person asked to be emailed."
                                    },
                                    "source": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 50,
                                        "description": "Optional. Where this contact came from, in your own words (up to 50 characters), like `checkout`.",
                                        "x-example": "checkout"
                                    },
                                    "consented_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "When this person agreed to be emailed, in ISO 8601. Bring it when you move from another service: it is your proof of consent.",
                                        "x-example": "2026-03-14T10:22:00Z"
                                    },
                                    "consent_ip": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 45,
                                        "description": "The IP address the agreement came from. IPv4 or IPv6.",
                                        "x-example": "203.0.113.10"
                                    },
                                    "consent_source": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Where they agreed, in your own words: a form name, a checkout step, \"imported from Mailchimp\".",
                                        "x-example": "Website footer form"
                                    },
                                    "check": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Send `\"wait\"` to have the address checked before we answer (up to about 8 seconds), so `email_status` in the reply is already the result. Any other value is ignored.",
                                        "x-example": "wait"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Their new email address."
                                    }
                                }
                            },
                            "example": {
                                "name": "Ada Obi",
                                "attributes": {
                                    "city": "Abuja"
                                }
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "patch": {
                "operationId": "patchContactsContact",
                "summary": "Update a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the contact."
                                                        },
                                                        "email": {
                                                            "type": "string",
                                                            "format": "email",
                                                            "description": "Lower-cased and trimmed on write, so the address you read back may not be byte-identical to the one you sent."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The contact's name. Null when none was given; `{{ name }}` is then empty unless your template gives a fallback."
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "subscribed",
                                                                "unsubscribed",
                                                                "bounced",
                                                                "complained",
                                                                "suppressed"
                                                            ],
                                                            "description": "Whether this contact will be emailed. `subscribed` means yes; any other value is the reason not. It combines the contact's `status` with your suppression list, so a subscribed contact whose address is suppressed reads `suppressed`. Read-only: you set `status` (`subscribed`, `unsubscribed`, `bounced` or `complained`) instead. Note that `?status=` filters on `status`, not on this."
                                                        },
                                                        "email_status": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "pending",
                                                                "valid",
                                                                "risky",
                                                                "invalid",
                                                                "unknown",
                                                                "not_checked"
                                                            ],
                                                            "description": "The result of checking whether the mailbox exists. `valid`: it exists. `invalid`: it does not. `risky`: it may not take mail (a catch-all domain, a role address such as info@, a throwaway address or a full inbox). `unknown`: the check could not tell. `pending`: being checked. `not_checked`: added after Bounce protection launched and not checked. Null: never checked, from before Bounce protection launched. Read-only; filter with `?email_status=`."
                                                        },
                                                        "email_full_until": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "Until when marketing to this contact is held because their inbox is full. When a check finds the inbox full, marketing waits 7 days; near the end it is checked again for free and the hold either ends or runs another 7 days. App email is never held. Null means no hold. Read-only."
                                                        },
                                                        "fields": {
                                                            "type": "object",
                                                            "additionalProperties": {
                                                                "type": "string"
                                                            },
                                                            "description": "Custom field values, keyed by the field's `key` (the name `{{ signup_date }}` uses). Always an object, `{}` when empty. Values are strings as stored; field defaults are not filled in here. When writing, send these as `attributes`."
                                                        },
                                                        "lists": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "The lists this contact is on, with their names. When writing, send list IDs as `list_ids`."
                                                        },
                                                        "tags": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            },
                                                            "description": "Your labels on this contact, with their names."
                                                        },
                                                        "interests": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "description": "What this contact chose on a form, each with the question it answers. `[]` means they chose nothing.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Match on this in a segment rule, never on the name."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The answer, as the contact read it."
                                                                    },
                                                                    "category_id": {
                                                                        "type": "string",
                                                                        "description": "The question this answers."
                                                                    },
                                                                    "category_title": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The question in words. `null` MEANS NOT INCLUDED \u2014 the category was not loaded, never that the question has no title."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "consent": {
                                                            "type": "object",
                                                            "description": "How this contact agreed to be emailed. Each field is null when we have no record. Set it when you import from another service, so your proof of consent comes with your contacts.",
                                                            "properties": {
                                                                "at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When they agreed. Null when unknown."
                                                                },
                                                                "ip": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The IP address they agreed from. Null when unknown."
                                                                },
                                                                "source": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Where they agreed, such as a form name, a URL or \"imported from Mailchimp\". Null when unknown."
                                                                }
                                                            }
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "How this contact was added: `manual`, `import_api`, `import_csv` or your own text (up to 50 characters). Null when nothing was recorded."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        },
                        "headers": {
                            "X-Mailyte-Checks-Remaining": {
                                "description": "The checks your account has left after this request: this month's plan checks, then bought checks, then send credits bought before checks launched, all counted in checks. Sent only once Bounce protection is on for your account.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "X-Mailyte-Checks-Warning": {
                                "description": "`running_low`: at your pace of the last 7 days the checks last under a week, or 80% of this month's plan checks are used and you have none bought. `ran_out`: no checks are left and a new contact this month could not be checked, so it was added as `not_checked`. Absent when neither applies, and until Bounce protection is on for your account.",
                                "schema": {
                                    "type": "string",
                                    "enum": [
                                        "running_low",
                                        "ran_out"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Change a contact's details. Send only the fields you want to change.\n\n**Lists are not changed here.** To add someone to a list use `POST /contact-lists/{id}/members`, or `PUT /contacts` with `list_ids`.\n\n**Checks.** Once Bounce protection is on for your account, a new contact, or a contact whose address\nchanges, is checked in the background with one check: its `email_status` reads `pending` until the\nanswer lands, then `valid`, `risky`, `invalid` (and the contact becomes `bounced`) or `unknown`. With\nBounce protection switched off, or no checks left, the contact is still saved, as `not_checked`. A\ncontact from an event (`unconfirmed`) is checked when it becomes `subscribed`. The write never fails\nbecause of a check.\n\nSend `\"check\": \"wait\"` to have the address checked before we answer (up to about 8 seconds), so the\n`email_status` in the reply is already the answer. Any other value is ignored. If the checker is\nslow, the contact is saved and checked in the background; if no checks are left, it is saved as\n`not_checked`.\n\nThe reply carries `X-Mailyte-Checks-Remaining` and, when it applies, `X-Mailyte-Checks-Warning:\nrunning_low | ran_out`. Neither is sent until Bounce protection is on for your account.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The person's name, as it should appear in your emails (`{{name}}`).",
                                        "example": "Ada Obi",
                                        "x-example": "Spring newsletter"
                                    },
                                    "attributes": {
                                        "nullable": true,
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "Custom fields as key\u2013value pairs. This REPLACES all of the contact's custom fields: send every field you want to keep.",
                                        "example": {
                                            "city": "Abuja"
                                        },
                                        "x-example": {
                                            "city": "Lagos"
                                        }
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "subscribed",
                                            "unsubscribed",
                                            "bounced",
                                            "complained"
                                        ],
                                        "description": "Change their status. Set `subscribed` again only when the person asked to be emailed."
                                    },
                                    "source": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 50,
                                        "description": "Optional. Where this contact came from, in your own words (up to 50 characters), like `checkout`.",
                                        "x-example": "checkout"
                                    },
                                    "consented_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "When this person agreed to be emailed, in ISO 8601. Bring it when you move from another service: it is your proof of consent.",
                                        "x-example": "2026-03-14T10:22:00Z"
                                    },
                                    "consent_ip": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 45,
                                        "description": "The IP address the agreement came from. IPv4 or IPv6.",
                                        "x-example": "203.0.113.10"
                                    },
                                    "consent_source": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Where they agreed, in your own words: a form name, a checkout step, \"imported from Mailchimp\".",
                                        "x-example": "Website footer form"
                                    },
                                    "check": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Send `\"wait\"` to have the address checked before we answer (up to about 8 seconds), so `email_status` in the reply is already the result. Any other value is ignored.",
                                        "x-example": "wait"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Their new email address."
                                    }
                                }
                            },
                            "example": {
                                "name": "Ada Obi",
                                "attributes": {
                                    "city": "Abuja"
                                }
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteContactsContact",
                "summary": "Delete a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The contact is gone; the confirmation is the envelope message."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/contact-lists": {
            "get": {
                "operationId": "getContactLists",
                "summary": "List contact lists",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "contact_list"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Unique identifier for the list."
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Your note on what the list is for. Null when none was written."
                                                                    },
                                                                    "contact_count": {
                                                                        "type": "integer",
                                                                        "description": "Every member of the list, including unsubscribed ones. For the members who can be emailed, use `GET /contacts?list_id=\u2026` and filter on `state`."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postContactLists",
                "summary": "Create a contact list",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_list"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the list."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note on what the list is for. Null when none was written."
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "description": "Every member of the list, including unsubscribed ones. For the members who can be emailed, use `GET /contacts?list_id=\u2026` and filter on `state`."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Its name, shown in the dashboard.",
                                        "x-example": "Spring newsletter"
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    }
                                }
                            },
                            "example": {
                                "name": "Newsletter subscribers",
                                "description": "Opted in via the footer form"
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/contact-lists/{contact_list}": {
            "get": {
                "operationId": "getContactListsContactList",
                "summary": "Retrieve a contact list",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact_list",
                        "in": "path",
                        "required": true,
                        "description": "The contact list identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_list"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the list."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note on what the list is for. Null when none was written."
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "description": "Every member of the list, including unsubscribed ones. For the members who can be emailed, use `GET /contacts?list_id=\u2026` and filter on `state`."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putContactListsContactList",
                "summary": "Update a contact list",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact_list",
                        "in": "path",
                        "required": true,
                        "description": "The contact list identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_list"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the list."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note on what the list is for. Null when none was written."
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "description": "Every member of the list, including unsubscribed ones. For the members who can be emailed, use `GET /contacts?list_id=\u2026` and filter on `state`."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Only `name` and `description` are editable. Membership is changed through the members routes, not by sending contacts here.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Its name, shown in the dashboard.",
                                        "x-example": "Spring newsletter"
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    }
                                }
                            },
                            "example": {
                                "name": "Newsletter subscribers (2026)"
                            }
                        }
                    }
                }
            },
            "patch": {
                "operationId": "patchContactListsContactList",
                "summary": "Update a contact list",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact_list",
                        "in": "path",
                        "required": true,
                        "description": "The contact list identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_list"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the list."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note on what the list is for. Null when none was written."
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "description": "Every member of the list, including unsubscribed ones. For the members who can be emailed, use `GET /contacts?list_id=\u2026` and filter on `state`."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Only `name` and `description` are editable. Membership is changed through the members routes, not by sending contacts here.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Its name, shown in the dashboard.",
                                        "x-example": "Spring newsletter"
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    }
                                }
                            },
                            "example": {
                                "name": "Newsletter subscribers (2026)"
                            }
                        }
                    }
                }
            },
            "delete": {
                "operationId": "deleteContactListsContactList",
                "summary": "Delete a contact list",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact_list",
                        "in": "path",
                        "required": true,
                        "description": "The contact list identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The list is gone; its members are not \u2014 deleting a list does not delete the contacts on it."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/contact-lists/{contactList}/members": {
            "post": {
                "operationId": "postContactListsContactListMembers",
                "summary": "Add contacts to a list",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contactList",
                        "in": "path",
                        "required": true,
                        "description": "The contact list identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The same counts for adding and for removing members; the ones that do not apply are 0.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_list_membership"
                                                            ]
                                                        },
                                                        "list_id": {
                                                            "type": "string",
                                                            "description": "The list this happened to, echoed from the path so the response can be logged on its own."
                                                        },
                                                        "added": {
                                                            "type": "integer",
                                                            "description": "Newly attached. Re-adding an existing member is a no-op that still counts as added \u2014 the request \"this contact is on this list\" was satisfied either way. Zero on a removal."
                                                        },
                                                        "removed": {
                                                            "type": "integer",
                                                            "description": "Detached. Removing somebody who was not a member is a no-op and counts 0. Zero on an add."
                                                        },
                                                        "skipped": {
                                                            "type": "integer",
                                                            "description": "IDs that matched no contact in your account, and were ignored."
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "description": "The size of the list AFTER the change, so you never have to follow up with a GET. Counts every member whatever their state, exactly as `contact_list.contact_count` does."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Adds existing contacts to a list. This does **not** create contacts \u2014 create them first with\n`POST /api/v1/contacts`, then add them here by id.\n\nAdding somebody who is already on the list is a no-op rather than an error or a duplicate, so\nthis is safe to call repeatedly with the same payload.\n\nIds that do not belong to your organization are ignored rather than rejected, and counted in\n`skipped`. They are not named: saying which ids were unknown would confirm which ids exist in\nsomebody else's account. If `skipped` comes back non-zero, check the ids you sent.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "contact_ids"
                                ],
                                "properties": {
                                    "contact_ids": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Ids of contacts that already exist in your organization."
                                    }
                                }
                            },
                            "example": {
                                "contact_ids": [
                                    "01m2q1qc6skqy6k2sq88abm4pw",
                                    "01m2r4sx6d2h67srjk6knwjczp"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/contact-lists/{contactList}/members/{contact}": {
            "delete": {
                "operationId": "deleteContactListsContactListMembersContact",
                "summary": "Remove a contact from a list",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contactList",
                        "in": "path",
                        "required": true,
                        "description": "The contact list identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The same counts for adding and for removing members; the ones that do not apply are 0.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_list_membership"
                                                            ]
                                                        },
                                                        "list_id": {
                                                            "type": "string",
                                                            "description": "The list this happened to, echoed from the path so the response can be logged on its own."
                                                        },
                                                        "added": {
                                                            "type": "integer",
                                                            "description": "Newly attached. Re-adding an existing member is a no-op that still counts as added \u2014 the request \"this contact is on this list\" was satisfied either way. Zero on a removal."
                                                        },
                                                        "removed": {
                                                            "type": "integer",
                                                            "description": "Detached. Removing somebody who was not a member is a no-op and counts 0. Zero on an add."
                                                        },
                                                        "skipped": {
                                                            "type": "integer",
                                                            "description": "IDs that matched no contact in your account, and were ignored."
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "description": "The size of the list AFTER the change, so you never have to follow up with a GET. Counts every member whatever their state, exactly as `contact_list.contact_count` does."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Takes one contact off a list. The contact itself is **not** deleted and its other list\nmemberships are untouched \u2014 to delete the contact entirely, use\n`DELETE /api/v1/contacts/{contact}`.\n\nRemoving somebody who was not on the list is a no-op, answering `removed: 0`."
            }
        },
        "/api/v1/contact-tags": {
            "get": {
                "operationId": "getContactTags",
                "summary": "List contact tags",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "contact_tag"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "description": "Unique identifier for the tag."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "The label as it was first written. Tags are matched case-insensitively \u2014 \"VIP\" and \"vip\" are one tag \u2014 and the spelling kept is whichever was used first, so a contact never shows two chips for the same label."
                                                            },
                                                            "contact_count": {
                                                                "type": "integer",
                                                                "nullable": true,
                                                                "description": "How many contacts have this tag. Null when the tag is shown as part of a contact."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postContactTags",
                "summary": "Create a contact tag",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_tag"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the tag."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "The label as it was first written. Tags are matched case-insensitively \u2014 \"VIP\" and \"vip\" are one tag \u2014 and the spelling kept is whichever was used first, so a contact never shows two chips for the same label."
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "How many contacts have this tag. Null when the tag is shown as part of a contact."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "The tag, like `vip`. Case does not matter: `VIP` and `vip` are the same tag.",
                                        "example": "vip",
                                        "x-example": "Spring newsletter"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "vip"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/contact-tags/{tag}": {
            "delete": {
                "operationId": "deleteContactTagsTag",
                "summary": "Delete a contact tag",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "tag",
                        "in": "path",
                        "required": true,
                        "description": "The tag identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The tag is removed from every contact that carried it; the contacts themselves are untouched."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/contacts/{contact}/tags": {
            "post": {
                "operationId": "postContactsContactTags",
                "summary": "Tags a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "contact_tag"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "description": "Unique identifier for the tag."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "The label as it was first written. Tags are matched case-insensitively \u2014 \"VIP\" and \"vip\" are one tag \u2014 and the spelling kept is whichever was used first, so a contact never shows two chips for the same label."
                                                            },
                                                            "contact_count": {
                                                                "type": "integer",
                                                                "nullable": true,
                                                                "description": "How many contacts have this tag. Null when the tag is shown as part of a contact."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "add": {
                                        "nullable": true,
                                        "type": "array",
                                        "maxItems": 50,
                                        "items": {
                                            "type": "string",
                                            "maxLength": 100
                                        },
                                        "description": "Tags to put on the contact, by name. A tag that does not exist yet is created.",
                                        "x-example": [
                                            "vip"
                                        ]
                                    },
                                    "remove": {
                                        "nullable": true,
                                        "type": "array",
                                        "maxItems": 50,
                                        "items": {
                                            "type": "string",
                                            "maxLength": 100
                                        },
                                        "description": "Tags to take off the contact, by name.",
                                        "x-example": [
                                            "trial"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "add": [
                                    "vip"
                                ],
                                "remove": [
                                    "trial"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/interest-categories": {
            "get": {
                "operationId": "getInterestCategories",
                "summary": "List interest categorys",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "interest_category"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string"
                                                            },
                                                            "title": {
                                                                "type": "string",
                                                                "description": "The question, as a contact reads it on a signup form \u2014 usually phrased as one: \"What do you want to hear about?\""
                                                            },
                                                            "type": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "checkboxes",
                                                                    "dropdown",
                                                                    "radio",
                                                                    "hidden"
                                                                ],
                                                                "description": "How the group shows on a form. `hidden` keeps it off forms, so it can only be set through the API. This shapes the form only: a `radio` group can still hold more than one answer if set another way."
                                                            },
                                                            "display_order": {
                                                                "type": "integer",
                                                                "description": "Position on the form, lower first."
                                                            },
                                                            "interests": {
                                                                "type": "array",
                                                                "nullable": true,
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "id": {
                                                                            "type": "string"
                                                                        },
                                                                        "name": {
                                                                            "type": "string"
                                                                        },
                                                                        "display_order": {
                                                                            "type": "integer"
                                                                        }
                                                                    }
                                                                },
                                                                "description": "The answers a contact can choose in this group."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postInterestCategories",
                "summary": "Create a interest category",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "interest_category"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "title": {
                                                            "type": "string",
                                                            "description": "The question, as a contact reads it on a signup form \u2014 usually phrased as one: \"What do you want to hear about?\""
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "checkboxes",
                                                                "dropdown",
                                                                "radio",
                                                                "hidden"
                                                            ],
                                                            "description": "How the group shows on a form. `hidden` keeps it off forms, so it can only be set through the API. This shapes the form only: a `radio` group can still hold more than one answer if set another way."
                                                        },
                                                        "display_order": {
                                                            "type": "integer",
                                                            "description": "Position on the form, lower first."
                                                        },
                                                        "interests": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "display_order": {
                                                                        "type": "integer"
                                                                    }
                                                                }
                                                            },
                                                            "description": "The answers a contact can choose in this group."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "The heading people see above the answers, like \"What would you like to hear about?\".",
                                        "x-example": "What would you like to hear about?"
                                    },
                                    "display_order": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 9999,
                                        "description": "Where this group appears among your groups, lowest first.",
                                        "x-example": 1
                                    },
                                    "interests": {
                                        "nullable": true,
                                        "type": "array",
                                        "maxItems": 60,
                                        "items": {
                                            "type": "string",
                                            "maxLength": 100
                                        },
                                        "example": [
                                            "Product updates",
                                            "Events"
                                        ],
                                        "description": "The answers people can pick in this group, like `Product updates`.",
                                        "x-example": [
                                            "Product updates",
                                            "Events"
                                        ]
                                    },
                                    "type": {
                                        "nullable": true,
                                        "type": "string",
                                        "enum": [
                                            "checkboxes",
                                            "dropdown",
                                            "radio",
                                            "hidden"
                                        ],
                                        "description": "How the group shows on a signup form. A `hidden` group is never shown: you set its answers from your own system.",
                                        "example": "checkboxes"
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            },
                            "example": {
                                "title": "What would you like to hear about?",
                                "interests": [
                                    "Product updates",
                                    "Events"
                                ],
                                "type": "checkboxes"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/interest-categories/{category}": {
            "delete": {
                "operationId": "deleteInterestCategoriesCategory",
                "summary": "Delete a interest category",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "category",
                        "in": "path",
                        "required": true,
                        "description": "The category identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The category, its interests and every contact's answers to it are removed \u2014 once the question is gone there is nothing for an answer to be an answer to."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/contacts/{contact}/interests": {
            "put": {
                "operationId": "putContactsContactInterests",
                "summary": "Interests a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "interest"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string"
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "The answer, as a contact reads it."
                                                            },
                                                            "category": {
                                                                "type": "object",
                                                                "description": "The question this answers. Included because an answer alone is ambiguous \u2014 \"Events\" means nothing until you know which question it belongs to.",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The category's ID."
                                                                    },
                                                                    "title": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The category's ID."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "interest_ids": {
                                        "type": "array",
                                        "maxItems": 200,
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "The answers this contact chose, by ID. This REPLACES their answers: send an empty list to clear them. Each answer copies its ID from Contacts \u2192 Groups in the dashboard.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "interest_ids": [
                                    "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/contact-fields": {
            "get": {
                "operationId": "getContactFields",
                "summary": "List contact fields",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "description": "One usable key of a contact's `fields` object. Serves both `GET /contact-fields` (the declared catalog) and `GET /contacts/attribute-keys` (the catalog plus keys observed on contact data), which is why `declared` exists.",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "contact_field"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "The definition's id, for `PUT`/`DELETE /contact-fields/{field}`. `null` when `declared` is false \u2014 there is no definition row, so there is nothing to address."
                                                            },
                                                            "key": {
                                                                "type": "string",
                                                                "description": "The stable name. This is the key inside a contact's `fields` object and the `{{ signup_date }}` tag in campaign content. Contact values are keyed by this, never by `id`."
                                                            },
                                                            "declared": {
                                                                "type": "boolean",
                                                                "description": "Whether this key is defined as a contact field (with a label, type and default), or was only seen on contact data. Both can be used in content and segment rules."
                                                            },
                                                            "label": {
                                                                "type": "string",
                                                                "description": "Display name. Derived from the key for an undeclared one."
                                                            },
                                                            "type": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "text",
                                                                    "number",
                                                                    "date",
                                                                    "boolean"
                                                                ],
                                                                "description": "How a value should be EDITED and displayed. Not a storage type: every value in a contact's `fields` object is a string whatever this says, and nothing is coerced."
                                                            },
                                                            "required": {
                                                                "type": "boolean",
                                                                "description": "Whether every contact must have a value. Checked when a contact is created, and when an update would clear the value; existing contacts are not checked. A default value does not count. Always false for a key that is not defined."
                                                            },
                                                            "default_value": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "Substituted at send time for contacts with no value of their own. It is never written into a contact's `fields`."
                                                            },
                                                            "help_text": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "The hint shown beside this field on a form. `null` MEANS NONE WAS WRITTEN \u2014 it carries no behaviour, so an absent hint changes nothing about what the field accepts."
                                                            },
                                                            "contacts_with_value": {
                                                                "type": "integer",
                                                                "description": "How many contacts carry a non-empty value for this key \u2014 the \"is it safe to delete this\" signal. Always an integer."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true,
                                                                "description": "`null` when `declared` is false: an observed key has no definition row and therefore no creation time. Genuinely unknown, not zero."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postContactFields",
                "summary": "Create a contact field",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "One usable key of a contact's `fields` object. Serves both `GET /contact-fields` (the declared catalog) and `GET /contacts/attribute-keys` (the catalog plus keys observed on contact data), which is why `declared` exists.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_field"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The definition's id, for `PUT`/`DELETE /contact-fields/{field}`. `null` when `declared` is false \u2014 there is no definition row, so there is nothing to address."
                                                        },
                                                        "key": {
                                                            "type": "string",
                                                            "description": "The stable name. This is the key inside a contact's `fields` object and the `{{ signup_date }}` tag in campaign content. Contact values are keyed by this, never by `id`."
                                                        },
                                                        "declared": {
                                                            "type": "boolean",
                                                            "description": "Whether this key is defined as a contact field (with a label, type and default), or was only seen on contact data. Both can be used in content and segment rules."
                                                        },
                                                        "label": {
                                                            "type": "string",
                                                            "description": "Display name. Derived from the key for an undeclared one."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "text",
                                                                "number",
                                                                "date",
                                                                "boolean"
                                                            ],
                                                            "description": "How a value should be EDITED and displayed. Not a storage type: every value in a contact's `fields` object is a string whatever this says, and nothing is coerced."
                                                        },
                                                        "required": {
                                                            "type": "boolean",
                                                            "description": "Whether every contact must have a value. Checked when a contact is created, and when an update would clear the value; existing contacts are not checked. A default value does not count. Always false for a key that is not defined."
                                                        },
                                                        "default_value": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Substituted at send time for contacts with no value of their own. It is never written into a contact's `fields`."
                                                        },
                                                        "help_text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The hint shown beside this field on a form. `null` MEANS NONE WAS WRITTEN \u2014 it carries no behaviour, so an absent hint changes nothing about what the field accepts."
                                                        },
                                                        "contacts_with_value": {
                                                            "type": "integer",
                                                            "description": "How many contacts carry a non-empty value for this key \u2014 the \"is it safe to delete this\" signal. Always an integer."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "`null` when `declared` is false: an observed key has no definition row and therefore no creation time. Genuinely unknown, not zero."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Declares one key of a contact's `fields` object: its label, its type, whether it is\nrequired, the value to fall back on and the hint to show beside it.\n\n**Declaring is optional.** A contact may carry any attribute key you write, declared or not,\nand an undeclared key works in content and in segment rules exactly the same. What a\ndeclaration adds is a label, a default at send time, a place in the field picker, and the\noption of requiring it. `declared` on the field object tells you which kind you are looking\nat.\n\n**`required` is enforced in two places and only two.** A contact being CREATED must supply\nit, and an update may not CLEAR a value that was already there. It is never checked\nretroactively, so marking a long-standing field required does not start rejecting contacts\nthat predate the decision \u2014 which is the only way anyone could safely turn it on for a live\naudience. In an import, a row with no value for a required field comes back in `errors[]`\nwith reason `missing_required_field`; the rest of the file still imports.\n\n**`default_value` does not satisfy `required`.** The default is substituted at render time\nfor a contact who has no value of their own and is never written to the contact. Accepting a\nplaceholder for a field you marked required would be the opposite of what you asked for.\n\nAn organization may hold 100 field definitions. The 101st is refused with the count and the\ncap in the message.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "label"
                                ],
                                "properties": {
                                    "label": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "description": "The display name."
                                    },
                                    "key": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "description": "The field's name in a contact's `fields` and in `{{ tag }}` content: lowercase letters, numbers and underscores, starting with a letter. Leave it out and we make one from the label (\"Signup Date\" becomes `signup_date`). It cannot be changed later."
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "text",
                                            "number",
                                            "date",
                                            "boolean"
                                        ],
                                        "description": "How a value should be EDITED and displayed. Not a storage type \u2014 every value is a string whatever this says, and nothing is coerced."
                                    },
                                    "required": {
                                        "type": "boolean",
                                        "description": "Whether every contact must carry a value. Defaults to false."
                                    },
                                    "default_value": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Substituted at send time for a contact with no value of their own. Never written to the contact."
                                    },
                                    "help_text": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The hint shown beside the input on a form. No behaviour."
                                    }
                                }
                            },
                            "example": {
                                "label": "Company",
                                "type": "text",
                                "required": true,
                                "help_text": "The organisation they work for"
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/contact-fields/{field}": {
            "put": {
                "operationId": "putContactFieldsField",
                "summary": "Update a contact field",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "field",
                        "in": "path",
                        "required": true,
                        "description": "The field identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "One usable key of a contact's `fields` object. Serves both `GET /contact-fields` (the declared catalog) and `GET /contacts/attribute-keys` (the catalog plus keys observed on contact data), which is why `declared` exists.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "contact_field"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The definition's id, for `PUT`/`DELETE /contact-fields/{field}`. `null` when `declared` is false \u2014 there is no definition row, so there is nothing to address."
                                                        },
                                                        "key": {
                                                            "type": "string",
                                                            "description": "The stable name. This is the key inside a contact's `fields` object and the `{{ signup_date }}` tag in campaign content. Contact values are keyed by this, never by `id`."
                                                        },
                                                        "declared": {
                                                            "type": "boolean",
                                                            "description": "Whether this key is defined as a contact field (with a label, type and default), or was only seen on contact data. Both can be used in content and segment rules."
                                                        },
                                                        "label": {
                                                            "type": "string",
                                                            "description": "Display name. Derived from the key for an undeclared one."
                                                        },
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "text",
                                                                "number",
                                                                "date",
                                                                "boolean"
                                                            ],
                                                            "description": "How a value should be EDITED and displayed. Not a storage type: every value in a contact's `fields` object is a string whatever this says, and nothing is coerced."
                                                        },
                                                        "required": {
                                                            "type": "boolean",
                                                            "description": "Whether every contact must have a value. Checked when a contact is created, and when an update would clear the value; existing contacts are not checked. A default value does not count. Always false for a key that is not defined."
                                                        },
                                                        "default_value": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Substituted at send time for contacts with no value of their own. It is never written into a contact's `fields`."
                                                        },
                                                        "help_text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The hint shown beside this field on a form. `null` MEANS NONE WAS WRITTEN \u2014 it carries no behaviour, so an absent hint changes nothing about what the field accepts."
                                                        },
                                                        "contacts_with_value": {
                                                            "type": "integer",
                                                            "description": "How many contacts carry a non-empty value for this key \u2014 the \"is it safe to delete this\" signal. Always an integer."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "`null` when `declared` is false: an observed key has no definition row and therefore no creation time. Genuinely unknown, not zero."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "label": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "description": "The display name."
                                    },
                                    "required": {
                                        "type": "boolean",
                                        "description": "Whether every contact must carry a value."
                                    },
                                    "default_value": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Used at send time for a contact with no value of their own."
                                    },
                                    "help_text": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The hint shown beside the input on a form."
                                    },
                                    "type": {
                                        "type": "string",
                                        "description": "How a value is edited and shown: `text`, `number`, `date` or `boolean`."
                                    }
                                }
                            },
                            "example": {
                                "label": "label",
                                "required": true
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteContactFieldsField",
                "summary": "Delete a contact field",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "field",
                        "in": "path",
                        "required": true,
                        "description": "The field identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The definition is gone; contacts keep any values stored under that key, which then read as an undeclared key."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/segments": {
            "get": {
                "operationId": "getSegments",
                "summary": "List segments",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "segment"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "description": "Unique identifier for the segment."
                                                            },
                                                            "name": {
                                                                "type": "string"
                                                            },
                                                            "description": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "Your note on what the segment is for. Null when none was written. It does not affect the rules."
                                                            },
                                                            "match": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "all",
                                                                    "any"
                                                                ],
                                                                "description": "How the rules combine: `all` of them must hold, or `any` one."
                                                            },
                                                            "rules": {
                                                                "type": "array",
                                                                "description": "The segment's rules, as you wrote them.",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "field": {
                                                                            "type": "string",
                                                                            "description": "What the rule tests: `email`, `name` or `status`; `opened`, `clicked` or `emailed` (from email activity); or any key in the contact's `fields`. `status` is the stored status, not the contact's `state`."
                                                                        },
                                                                        "op": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "equals",
                                                                                "not_equals",
                                                                                "contains",
                                                                                "not_contains",
                                                                                "is_set",
                                                                                "is_not_set",
                                                                                "starts_with",
                                                                                "ends_with",
                                                                                "greater_than",
                                                                                "less_than",
                                                                                "before",
                                                                                "after",
                                                                                "within_days",
                                                                                "not_within_days"
                                                                            ],
                                                                            "description": "How the rule compares.\n\n- `within_days`, `not_within_days`: only with `opened`, `clicked` or `emailed`. `not_within_days` includes contacts never emailed.\n- `greater_than`, `less_than`: compare as numbers.\n- `before`, `after`: compare as dates.\n- `starts_with`, `ends_with`: match the start or end of the value, not anywhere in it.\n\nA value that cannot be read as the right type matches nothing."
                                                                        },
                                                                        "value": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "What to compare with. Null for `is_set` and `is_not_set`; a number of days from 1 to 365 for the activity operators."
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "contact_count": {
                                                                "type": "integer",
                                                                "description": "LIVE. A segment is a query, so this is what the rules match now, not what they matched when it was saved. Always an integer."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            },
                                                            "updated_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postSegments",
                "summary": "Create a segment",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "segment"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the segment."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note on what the segment is for. Null when none was written. It does not affect the rules."
                                                        },
                                                        "match": {
                                                            "type": "string",
                                                            "enum": [
                                                                "all",
                                                                "any"
                                                            ],
                                                            "description": "How the rules combine: `all` of them must hold, or `any` one."
                                                        },
                                                        "rules": {
                                                            "type": "array",
                                                            "description": "The segment's rules, as you wrote them.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "What the rule tests: `email`, `name` or `status`; `opened`, `clicked` or `emailed` (from email activity); or any key in the contact's `fields`. `status` is the stored status, not the contact's `state`."
                                                                    },
                                                                    "op": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "equals",
                                                                            "not_equals",
                                                                            "contains",
                                                                            "not_contains",
                                                                            "is_set",
                                                                            "is_not_set",
                                                                            "starts_with",
                                                                            "ends_with",
                                                                            "greater_than",
                                                                            "less_than",
                                                                            "before",
                                                                            "after",
                                                                            "within_days",
                                                                            "not_within_days"
                                                                        ],
                                                                        "description": "How the rule compares.\n\n- `within_days`, `not_within_days`: only with `opened`, `clicked` or `emailed`. `not_within_days` includes contacts never emailed.\n- `greater_than`, `less_than`: compare as numbers.\n- `before`, `after`: compare as dates.\n- `starts_with`, `ends_with`: match the start or end of the value, not anywhere in it.\n\nA value that cannot be read as the right type matches nothing."
                                                                    },
                                                                    "value": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "What to compare with. Null for `is_set` and `is_not_set`; a number of days from 1 to 365 for the activity operators."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "description": "LIVE. A segment is a query, so this is what the rules match now, not what they matched when it was saved. Always an integer."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    },
                                    "rules": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "field": {
                                                    "type": "string",
                                                    "maxLength": 64,
                                                    "description": "What to test: `email`, `name` or `status`; a custom field's key; `opened`, `clicked` or `emailed`; or `tag` or `interest`."
                                                },
                                                "op": {
                                                    "type": "string",
                                                    "enum": [
                                                        "equals",
                                                        "not_equals",
                                                        "contains",
                                                        "not_contains",
                                                        "is_set",
                                                        "is_not_set",
                                                        "starts_with",
                                                        "ends_with",
                                                        "greater_than",
                                                        "less_than",
                                                        "before",
                                                        "after",
                                                        "within_days",
                                                        "not_within_days"
                                                    ],
                                                    "description": "How to compare. `opened`, `clicked` and `emailed` take `within_days` or `not_within_days` only."
                                                },
                                                "value": {
                                                    "nullable": true,
                                                    "type": "string",
                                                    "maxLength": 255,
                                                    "description": "What to compare with: text, a number, a date, or a number of days (1 to 365) for `within_days`. Leave it out for `is_set` and `is_not_set`."
                                                }
                                            },
                                            "required": [
                                                "field",
                                                "op"
                                            ]
                                        },
                                        "description": "The tests a contact must pass. The table above lists the fields you can test.",
                                        "example": [
                                            {
                                                "field": "city",
                                                "op": "equals",
                                                "value": "Lagos"
                                            }
                                        ]
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Lagos customers`.",
                                        "example": "Lagos customers",
                                        "x-example": "Spring newsletter"
                                    },
                                    "match": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "any"
                                        ],
                                        "description": "`all`: a contact must match every rule. `any`: one rule is enough. Defaults to `all`.",
                                        "example": "all"
                                    }
                                }
                            },
                            "example": {
                                "rules": [
                                    {
                                        "field": "city",
                                        "op": "equals",
                                        "value": "Lagos"
                                    }
                                ],
                                "name": "Lagos customers",
                                "match": "all"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            }
        },
        "/api/v1/segments/preview": {
            "post": {
                "operationId": "postSegmentsPreview",
                "summary": "Preview a segment",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "segment_preview"
                                                            ]
                                                        },
                                                        "count": {
                                                            "type": "integer",
                                                            "description": "Every contact the rules match \u2014 exact, and NOT the size of `sample`."
                                                        },
                                                        "sample": {
                                                            "type": "array",
                                                            "description": "Up to five matching contacts, so you can check the audience is right. Save the segment to get every match.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "email": {
                                                                        "type": "string",
                                                                        "format": "email"
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The contact's name. Null when none is recorded."
                                                                    },
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "subscribed",
                                                                            "unsubscribed",
                                                                            "bounced",
                                                                            "complained",
                                                                            "suppressed"
                                                                        ],
                                                                        "description": "Literally `contact.state`, resolved by the same code against the same suppression list, so a preview can never disagree with the contact endpoint about who is mailable."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "How many contacts a set of rules currently matches, and a sample of them, without saving the\nsegment. Call this before sending to one.\n\n**Rules take one of four kinds of field:**\n\n| Kind | Fields | Example |\n|---|---|---|\n| Contact columns | `email`, `name`, `status` | `{\"field\": \"email\", \"op\": \"ends_with\", \"value\": \"@acme.com\"}` |\n| Custom fields | any key from `GET /contact-fields` | `{\"field\": \"plan\", \"op\": \"equals\", \"value\": \"pro\"}` |\n| Engagement | `opened`, `clicked`, `emailed` | `{\"field\": \"opened\", \"op\": \"within_days\", \"value\": \"90\"}` |\n| **Membership** | `tag`, `interest` | `{\"field\": \"tag\", \"op\": \"equals\", \"value\": \"vip\"}` |\n\n**`tag` matches by NAME, `interest` matches by ID.** That asymmetry is deliberate. A tag is\nwritten by name everywhere \u2014 created on first use, case-insensitively \u2014 so a rule holding a\nULID would break the moment somebody renamed it. An interest is an answer to a question the\n*contact* was asked and its name is form copy, so rewording \"Product updates\" must not\nsilently empty every segment built on it.\n\nMembership fields take `equals`, `not_equals`, `is_set` (has any) and `is_not_set` (has\nnone). Deliberately **not** `contains`: a tag is on a contact or it is not, and a substring\nmatch over a set would let `contains \"vip\"` quietly also match `vip-churn-risk`.\n\n**`not_equals` means \"does not carry it\", not \"carries something else\".** A contact with\nboth `vip` and `churn-risk` is EXCLUDED by `tag is not vip` \u2014 they carry it. A contact with\nno tags at all is included, because they do not.\n\nA rule we cannot evaluate \u2014 an unparseable number or date, a blank tag \u2014 matches **nothing**.\nWidening is the dangerous direction: it mails people who were never meant to be in the\naudience, and it does so quietly.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    },
                                    "rules": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "field": {
                                                    "type": "string",
                                                    "maxLength": 64,
                                                    "description": "What to test: `email`, `name` or `status`; a custom field's key; `opened`, `clicked` or `emailed`; or `tag` or `interest`."
                                                },
                                                "op": {
                                                    "type": "string",
                                                    "enum": [
                                                        "equals",
                                                        "not_equals",
                                                        "contains",
                                                        "not_contains",
                                                        "is_set",
                                                        "is_not_set",
                                                        "starts_with",
                                                        "ends_with",
                                                        "greater_than",
                                                        "less_than",
                                                        "before",
                                                        "after",
                                                        "within_days",
                                                        "not_within_days"
                                                    ],
                                                    "description": "How to compare. `opened`, `clicked` and `emailed` take `within_days` or `not_within_days` only."
                                                },
                                                "value": {
                                                    "nullable": true,
                                                    "type": "string",
                                                    "maxLength": 255,
                                                    "description": "What to compare with: text, a number, a date, or a number of days (1 to 365) for `within_days`. Leave it out for `is_set` and `is_not_set`."
                                                }
                                            },
                                            "required": [
                                                "field",
                                                "op"
                                            ]
                                        },
                                        "description": "The tests a contact must pass. The table above lists the fields you can test.",
                                        "example": [
                                            {
                                                "field": "city",
                                                "op": "equals",
                                                "value": "Lagos"
                                            }
                                        ]
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Lagos customers`.",
                                        "example": "Lagos customers",
                                        "x-example": "Spring newsletter"
                                    },
                                    "match": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "any"
                                        ],
                                        "description": "`all`: a contact must match every rule. `any`: one rule is enough. Defaults to `all`.",
                                        "example": "all"
                                    }
                                }
                            },
                            "example": {
                                "rules": [
                                    {
                                        "field": "city",
                                        "op": "equals",
                                        "value": "Lagos"
                                    }
                                ],
                                "name": "Lagos customers",
                                "match": "all"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            }
        },
        "/api/v1/segments/{segment}": {
            "put": {
                "operationId": "putSegmentsSegment",
                "summary": "Update a segment",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "segment",
                        "in": "path",
                        "required": true,
                        "description": "The segment identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "segment"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the segment."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note on what the segment is for. Null when none was written. It does not affect the rules."
                                                        },
                                                        "match": {
                                                            "type": "string",
                                                            "enum": [
                                                                "all",
                                                                "any"
                                                            ],
                                                            "description": "How the rules combine: `all` of them must hold, or `any` one."
                                                        },
                                                        "rules": {
                                                            "type": "array",
                                                            "description": "The segment's rules, as you wrote them.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "What the rule tests: `email`, `name` or `status`; `opened`, `clicked` or `emailed` (from email activity); or any key in the contact's `fields`. `status` is the stored status, not the contact's `state`."
                                                                    },
                                                                    "op": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "equals",
                                                                            "not_equals",
                                                                            "contains",
                                                                            "not_contains",
                                                                            "is_set",
                                                                            "is_not_set",
                                                                            "starts_with",
                                                                            "ends_with",
                                                                            "greater_than",
                                                                            "less_than",
                                                                            "before",
                                                                            "after",
                                                                            "within_days",
                                                                            "not_within_days"
                                                                        ],
                                                                        "description": "How the rule compares.\n\n- `within_days`, `not_within_days`: only with `opened`, `clicked` or `emailed`. `not_within_days` includes contacts never emailed.\n- `greater_than`, `less_than`: compare as numbers.\n- `before`, `after`: compare as dates.\n- `starts_with`, `ends_with`: match the start or end of the value, not anywhere in it.\n\nA value that cannot be read as the right type matches nothing."
                                                                    },
                                                                    "value": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "What to compare with. Null for `is_set` and `is_not_set`; a number of days from 1 to 365 for the activity operators."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "contact_count": {
                                                            "type": "integer",
                                                            "description": "LIVE. A segment is a query, so this is what the rules match now, not what they matched when it was saved. Always an integer."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Optional. A note for your team, shown in the dashboard.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    },
                                    "rules": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "field": {
                                                    "type": "string",
                                                    "maxLength": 64,
                                                    "description": "What to test: `email`, `name` or `status`; a custom field's key; `opened`, `clicked` or `emailed`; or `tag` or `interest`."
                                                },
                                                "op": {
                                                    "type": "string",
                                                    "enum": [
                                                        "equals",
                                                        "not_equals",
                                                        "contains",
                                                        "not_contains",
                                                        "is_set",
                                                        "is_not_set",
                                                        "starts_with",
                                                        "ends_with",
                                                        "greater_than",
                                                        "less_than",
                                                        "before",
                                                        "after",
                                                        "within_days",
                                                        "not_within_days"
                                                    ],
                                                    "description": "How to compare. `opened`, `clicked` and `emailed` take `within_days` or `not_within_days` only."
                                                },
                                                "value": {
                                                    "nullable": true,
                                                    "type": "string",
                                                    "maxLength": 255,
                                                    "description": "What to compare with: text, a number, a date, or a number of days (1 to 365) for `within_days`. Leave it out for `is_set` and `is_not_set`."
                                                }
                                            },
                                            "required": [
                                                "field",
                                                "op"
                                            ]
                                        },
                                        "description": "The tests a contact must pass. The table above lists the fields you can test.",
                                        "example": [
                                            {
                                                "field": "city",
                                                "op": "equals",
                                                "value": "Lagos"
                                            }
                                        ]
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Lagos customers`.",
                                        "example": "Lagos customers",
                                        "x-example": "Spring newsletter"
                                    },
                                    "match": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "any"
                                        ],
                                        "description": "`all`: a contact must match every rule. `any`: one rule is enough. Defaults to `all`.",
                                        "example": "all"
                                    }
                                }
                            },
                            "example": {
                                "rules": [
                                    {
                                        "field": "city",
                                        "op": "equals",
                                        "value": "Lagos"
                                    }
                                ],
                                "name": "Lagos customers",
                                "match": "all"
                            }
                        }
                    }
                },
                "x-body-source": "service-rules",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteSegmentsSegment",
                "summary": "Delete a segment",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "segment",
                        "in": "path",
                        "required": true,
                        "description": "The segment identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. A segment is a saved query, so deleting it removes the definition and touches no contact."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/contacts/{contact}/events": {
            "get": {
                "operationId": "getContactsContactEvents",
                "summary": "List a contact's events",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "contact_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "event": {
                                                                        "type": "string",
                                                                        "description": "The event name as it was sent, lowercase snake_case."
                                                                    },
                                                                    "properties": {
                                                                        "type": "object",
                                                                        "additionalProperties": true
                                                                    },
                                                                    "occurred_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "received_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "source": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "api",
                                                                            "system",
                                                                            "import"
                                                                        ]
                                                                    },
                                                                    "unique_id": {
                                                                        "type": "string",
                                                                        "description": "The deduplication key: yours if you sent one, otherwise derived."
                                                                    },
                                                                    "historical": {
                                                                        "type": "boolean",
                                                                        "description": "True when the event was older than the trigger window at receipt. Stored, never triggers an automation."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "The events recorded for one contact, newest first by `occurred_at`, including historical ones. The same list as the Events tab on the contact in the dashboard \u2014 the quickest way to check an integration is sending what you think it is."
            }
        },
        "/api/v1/contacts/{contact}/automation-runs": {
            "get": {
                "operationId": "getContactsContactAutomationRuns",
                "summary": "Automation Runs a contact",
                "tags": [
                    "Contacts"
                ],
                "x-required-scope": "contacts:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contact",
                        "in": "path",
                        "required": true,
                        "description": "The contact identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "automation_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "version_id": {
                                                                        "type": "string",
                                                                        "description": "The version this run entered. It finishes that version even if a newer one is published."
                                                                    },
                                                                    "version_number": {
                                                                        "type": "integer",
                                                                        "nullable": true
                                                                    },
                                                                    "contact": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "email": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            }
                                                                        }
                                                                    },
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "enrolled",
                                                                            "running",
                                                                            "waiting_time",
                                                                            "waiting_event",
                                                                            "paused",
                                                                            "completed",
                                                                            "exited",
                                                                            "failed"
                                                                        ]
                                                                    },
                                                                    "current_node_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "wake_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the engine next picks this run up. UTC."
                                                                    },
                                                                    "waiting_event": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "entered_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "ended_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true
                                                                    },
                                                                    "exit_reason": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why the run ended early: event:<name>, unsubscribed, archived, goal:<node>."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "context": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "additionalProperties": true,
                                                                        "description": "The trigger payload: the event properties, or the list or tag that started the run."
                                                                    },
                                                                    "automation": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "state": {
                                                                                "type": "string"
                                                                            }
                                                                        },
                                                                        "description": "Present on a contact's run list."
                                                                    },
                                                                    "summary": {
                                                                        "type": "string",
                                                                        "description": "One plain-language line about this run. Present on a contact's run list."
                                                                    },
                                                                    "steps": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "id": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "node_id": {
                                                                                    "type": "string",
                                                                                    "description": "The node in the version graph this step belongs to."
                                                                                },
                                                                                "node_type": {
                                                                                    "type": "string",
                                                                                    "description": "The node type, e.g. delay, send_email, trigger, exit_rule."
                                                                                },
                                                                                "occurred_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "outcome": {
                                                                                    "type": "string",
                                                                                    "enum": [
                                                                                        "enrolled",
                                                                                        "executed",
                                                                                        "sending",
                                                                                        "sent",
                                                                                        "skipped",
                                                                                        "deferred",
                                                                                        "branch",
                                                                                        "exited",
                                                                                        "failed",
                                                                                        "unknown"
                                                                                    ]
                                                                                },
                                                                                "branch_taken": {
                                                                                    "type": "string",
                                                                                    "nullable": true
                                                                                },
                                                                                "message_id": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "description": "The sent message, when this step sent one. Ties the step to delivery events."
                                                                                },
                                                                                "skipped_reason": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "description": "Why nothing was sent: `suppressed`, `unsubscribed`, `marketing_review_pending`, `rate_limited`, `not_mailable` or `inbox_full`. With `inbox_full`, marketing to this person is held until `details.email_full_until`."
                                                                                },
                                                                                "details": {
                                                                                    "type": "object",
                                                                                    "nullable": true,
                                                                                    "additionalProperties": true
                                                                                }
                                                                            }
                                                                        },
                                                                        "description": "Present when a single run is fetched; omitted from the list."
                                                                    },
                                                                    "narrative": {
                                                                        "type": "object",
                                                                        "description": "Present when a single run is fetched: the steps as sentences, in the contact's local time.",
                                                                        "properties": {
                                                                            "timezone": {
                                                                                "type": "string"
                                                                            },
                                                                            "tz_source": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "contact",
                                                                                    "organization_default",
                                                                                    "utc"
                                                                                ],
                                                                                "description": "Where the timezone came from: the contact's own attribute, the organisation default, or UTC."
                                                                            },
                                                                            "paragraphs": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                },
                                                                                "description": "One paragraph per local day, plus what never happened after an early exit."
                                                                            },
                                                                            "lines": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "object",
                                                                                    "properties": {
                                                                                        "node_id": {
                                                                                            "type": "string",
                                                                                            "nullable": true
                                                                                        },
                                                                                        "at": {
                                                                                            "type": "string",
                                                                                            "format": "date-time",
                                                                                            "nullable": true
                                                                                        },
                                                                                        "text": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "outcome": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "ghost": {
                                                                                            "type": "boolean",
                                                                                            "description": "True for a step that never ran because the run ended early."
                                                                                        }
                                                                                    }
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/campaigns": {
            "get": {
                "operationId": "getCampaigns",
                "summary": "List campaigns",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "campaign"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Unique identifier for the campaign."
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "draft",
                                                                            "scheduled",
                                                                            "sending",
                                                                            "paused",
                                                                            "sent",
                                                                            "canceled",
                                                                            "unknown"
                                                                        ],
                                                                        "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                                    },
                                                                    "sender": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The sender's display name."
                                                                            },
                                                                            "email": {
                                                                                "type": "string",
                                                                                "format": "email"
                                                                            }
                                                                        }
                                                                    },
                                                                    "content": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "subject": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                            },
                                                                            "template_id": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                            },
                                                                            "has_html": {
                                                                                "type": "boolean",
                                                                                "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                            },
                                                                            "has_text": {
                                                                                "type": "boolean",
                                                                                "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                            },
                                                                            "html": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                            },
                                                                            "text": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                            }
                                                                        }
                                                                    },
                                                                    "audience": {
                                                                        "type": "object",
                                                                        "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                                        "properties": {
                                                                            "lists": {
                                                                                "type": "array",
                                                                                "nullable": true,
                                                                                "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                                "items": {
                                                                                    "type": "object",
                                                                                    "properties": {
                                                                                        "id": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "name": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "contact_count": {
                                                                                            "type": "integer",
                                                                                            "nullable": true,
                                                                                            "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                                        }
                                                                                    }
                                                                                }
                                                                            },
                                                                            "segments": {
                                                                                "type": "array",
                                                                                "nullable": true,
                                                                                "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                                "items": {
                                                                                    "type": "object",
                                                                                    "properties": {
                                                                                        "id": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "name": {
                                                                                            "type": "string"
                                                                                        }
                                                                                    }
                                                                                }
                                                                            },
                                                                            "includes_unlisted": {
                                                                                "type": "boolean",
                                                                                "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                            },
                                                                            "excluded": {
                                                                                "type": "object",
                                                                                "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                                "properties": {
                                                                                    "count": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                                    },
                                                                                    "contact_ids": {
                                                                                        "type": "array",
                                                                                        "nullable": true,
                                                                                        "items": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                                    }
                                                                                }
                                                                            }
                                                                        }
                                                                    },
                                                                    "schedule": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "scheduled_for": {
                                                                                "type": "string",
                                                                                "format": "date-time",
                                                                                "nullable": true,
                                                                                "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                            },
                                                                            "started_at": {
                                                                                "type": "string",
                                                                                "format": "date-time",
                                                                                "nullable": true,
                                                                                "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                            },
                                                                            "completed_at": {
                                                                                "type": "string",
                                                                                "format": "date-time",
                                                                                "nullable": true,
                                                                                "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                            }
                                                                        }
                                                                    },
                                                                    "resent_from_campaign_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The campaign this one was resent from. Null when it is an original."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postCampaigns",
                "summary": "Create a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "A campaign is a bulk send to a list or segment, with unsubscribe handling, reporting\nand \u2014 for organizations new to marketing sending \u2014 a review step.\n\nCreating one does not send it. Schedule or send it explicitly, and call\n`preflight` first: it checks the things that get a campaign stopped, and it is far\ncheaper to fail there than halfway through a list.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `October newsletter`. Recipients never see it.",
                                        "example": "October newsletter",
                                        "x-example": "Spring newsletter"
                                    },
                                    "sender_id": {
                                        "type": "string",
                                        "description": "The ID of a verified sender, which sets the From name and address. Copy it from Sending \u2192 Senders in the dashboard, or read it from `GET /senders`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "subject": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The subject line. It can use `{{ tags }}` like `{{name}}`. Needed before the campaign can be sent.",
                                        "example": "Our October update",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "The email's HTML. Leave it out when you use `template_id`, or for a plain email (send `plain_text` alone).",
                                        "example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    },
                                    "plain_text": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "A plain email: send this alone, with no `html` or `template_id`, and we lay it out simply and add the unsubscribe line. Sent with `html`, it is that email's text version.",
                                        "x-example": "Hi {{name}},\n\nHere is what is new this month."
                                    },
                                    "template_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. Use one of your templates for the content instead of `html`. Copy its ID from Templates in the dashboard, or read it from `GET /email-templates`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "scheduled_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Optional. When you want it to go out, in ISO 8601 with a time zone. Saving it does not schedule anything: the campaign goes out only when you call `POST /campaigns/{id}/schedule` (pass the time there) or `POST /campaigns/{id}/send`.",
                                        "x-example": "2026-11-02T09:00:00+01:00"
                                    },
                                    "list_ids": {
                                        "nullable": true,
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "The lists to send to. Copy IDs from Contacts \u2192 Lists in the dashboard, or read them from `GET /contact-lists`.",
                                        "example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ],
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "segment_ids": {
                                        "nullable": true,
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "The segments to send to. Copy IDs from Contacts \u2192 Segments in the dashboard, or read them from `GET /segments`.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "include_unlisted": {
                                        "nullable": true,
                                        "type": "boolean",
                                        "description": "Also send to contacts who are on no list at all. Defaults to false.",
                                        "x-example": false
                                    },
                                    "excluded_contact_ids": {
                                        "nullable": true,
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Contacts to leave out even though they are on the chosen lists or segments, by contact ID.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    }
                                },
                                "required": [
                                    "name",
                                    "sender_id"
                                ]
                            },
                            "example": {
                                "name": "October newsletter",
                                "sender_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                "subject": "Our October update",
                                "html": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>",
                                "list_ids": [
                                    "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/campaigns/{campaign}": {
            "get": {
                "operationId": "getCampaignsCampaign",
                "summary": "Retrieve a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putCampaignsCampaign",
                "summary": "Update a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `October newsletter`. Recipients never see it.",
                                        "example": "October newsletter",
                                        "x-example": "Spring newsletter"
                                    },
                                    "sender_id": {
                                        "type": "string",
                                        "description": "The ID of a verified sender, which sets the From name and address. Copy it from Sending \u2192 Senders in the dashboard, or read it from `GET /senders`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "subject": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The subject line. It can use `{{ tags }}` like `{{name}}`. Needed before the campaign can be sent.",
                                        "example": "Our October update",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "The email's HTML. Leave it out when you use `template_id`, or for a plain email (send `plain_text` alone).",
                                        "example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    },
                                    "plain_text": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "A plain email: send this alone, with no `html` or `template_id`, and we lay it out simply and add the unsubscribe line. Sent with `html`, it is that email's text version.",
                                        "x-example": "Hi {{name}},\n\nHere is what is new this month."
                                    },
                                    "template_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. Use one of your templates for the content instead of `html`. Copy its ID from Templates in the dashboard, or read it from `GET /email-templates`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "scheduled_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Optional. When you want it to go out, in ISO 8601 with a time zone. Saving it does not schedule anything: the campaign goes out only when you call `POST /campaigns/{id}/schedule` (pass the time there) or `POST /campaigns/{id}/send`.",
                                        "x-example": "2026-11-02T09:00:00+01:00"
                                    },
                                    "list_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "The lists to send to. Copy IDs from Contacts \u2192 Lists in the dashboard, or read them from `GET /contact-lists`.",
                                        "example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ],
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "segment_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "The segments to send to. Copy IDs from Contacts \u2192 Segments in the dashboard, or read them from `GET /segments`.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "include_unlisted": {
                                        "type": "boolean",
                                        "description": "Also send to contacts who are on no list at all. Defaults to false.",
                                        "x-example": false
                                    },
                                    "excluded_contact_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Contacts to leave out even though they are on the chosen lists or segments, by contact ID.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "name": "October newsletter",
                                "subject": "Our October update",
                                "html": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>",
                                "list_ids": [
                                    "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            },
            "patch": {
                "operationId": "patchCampaignsCampaign",
                "summary": "Update a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `October newsletter`. Recipients never see it.",
                                        "example": "October newsletter",
                                        "x-example": "Spring newsletter"
                                    },
                                    "sender_id": {
                                        "type": "string",
                                        "description": "The ID of a verified sender, which sets the From name and address. Copy it from Sending \u2192 Senders in the dashboard, or read it from `GET /senders`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "subject": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "The subject line. It can use `{{ tags }}` like `{{name}}`. Needed before the campaign can be sent.",
                                        "example": "Our October update",
                                        "x-example": "Your October update"
                                    },
                                    "html": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "The email's HTML. Leave it out when you use `template_id`, or for a plain email (send `plain_text` alone).",
                                        "example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>",
                                        "x-example": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>"
                                    },
                                    "plain_text": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "A plain email: send this alone, with no `html` or `template_id`, and we lay it out simply and add the unsubscribe line. Sent with `html`, it is that email's text version.",
                                        "x-example": "Hi {{name}},\n\nHere is what is new this month."
                                    },
                                    "template_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. Use one of your templates for the content instead of `html`. Copy its ID from Templates in the dashboard, or read it from `GET /email-templates`.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "scheduled_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Optional. When you want it to go out, in ISO 8601 with a time zone. Saving it does not schedule anything: the campaign goes out only when you call `POST /campaigns/{id}/schedule` (pass the time there) or `POST /campaigns/{id}/send`.",
                                        "x-example": "2026-11-02T09:00:00+01:00"
                                    },
                                    "list_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "The lists to send to. Copy IDs from Contacts \u2192 Lists in the dashboard, or read them from `GET /contact-lists`.",
                                        "example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ],
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "segment_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "The segments to send to. Copy IDs from Contacts \u2192 Segments in the dashboard, or read them from `GET /segments`.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    },
                                    "include_unlisted": {
                                        "type": "boolean",
                                        "description": "Also send to contacts who are on no list at all. Defaults to false.",
                                        "x-example": false
                                    },
                                    "excluded_contact_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Contacts to leave out even though they are on the chosen lists or segments, by contact ID.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "name": "October newsletter",
                                "subject": "Our October update",
                                "html": "<p>Hi {{name}},</p><p>Here is what is new this month.</p>",
                                "list_ids": [
                                    "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteCampaignsCampaign",
                "summary": "Delete a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. Only a draft can be deleted \u2014 a paused campaign cannot, and resuming it is currently its only exit."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/campaigns/{campaign}/schedule": {
            "post": {
                "operationId": "postCampaignsCampaignSchedule",
                "summary": "Schedule a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "scheduled_at": {
                                        "nullable": true,
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "When to send, ISO 8601 with a timezone offset, like `2026-11-02T09:00:00+01:00`. Leave it out to send as soon as possible: a time saved on the campaign earlier is NOT used.",
                                        "example": "2026-11-02T09:00:00+01:00",
                                        "x-example": "2026-11-02T09:00:00+01:00"
                                    }
                                }
                            },
                            "example": {
                                "scheduled_at": "2026-11-02T09:00:00+01:00"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/campaigns/{campaign}/send": {
            "post": {
                "operationId": "postCampaignsCampaignSend",
                "summary": "Send a campaign now",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Begins the send immediately.\n\nMarketing mail rides a different egress path from transactional mail, deliberately, so\na newsletter cannot damage the reputation that carries your password resets. New\nmarketing senders are rate-limited while they warm up, so a large first campaign will\ntake longer than you expect \u2014 that is the system working.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/campaigns/{campaign}/pause": {
            "post": {
                "operationId": "postCampaignsCampaignPause",
                "summary": "Pause a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/campaigns/{campaign}/resume": {
            "post": {
                "operationId": "postCampaignsCampaignResume",
                "summary": "Resume a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/campaigns/{campaign}/cancel": {
            "post": {
                "operationId": "postCampaignsCampaignCancel",
                "summary": "Cancel a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "x-request-body": "none",
                "description": "This endpoint takes no request body."
            }
        },
        "/api/v1/campaigns/{campaign}/resend": {
            "post": {
                "operationId": "postCampaignsCampaignResend",
                "summary": "Resend a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The field SET never varies between a list and a single campaign. Two values do: `content.html` / `content.text` and `audience.excluded_contact_ids` are null in a list response. See those fields.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the campaign."
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "Where the campaign is.\n\n- `draft`: editable, not going anywhere.\n- `scheduled`: waiting for its send time.\n- `sending`: going out now.\n- `paused`: stopped partway and can be resumed.\n- `sent`: finished sending. Read `GET /campaigns/{campaign}/stats` for how many were delivered.\n- `canceled`: stopped for good, though it can be resent.\n- `unknown`: a state we did not recognise. Contact support.\n\nTo see whether a campaign can go out, use `POST /campaigns/{campaign}/preflight`."
                                                        },
                                                        "sender": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The sender this campaign sends as. Whether the sender is verified is checked by preflight.",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The sender's display name."
                                                                },
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email"
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "object",
                                                            "properties": {
                                                                "subject": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The subject line. Null when none has been written. A campaign with no subject and no template cannot be sent."
                                                                },
                                                                "template_id": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The template this campaign uses, if any. When a template is set, it is used instead of the campaign's own `subject`, `html` and `text`. Null when the campaign uses its own content."
                                                                },
                                                                "has_html": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `html !== null`."
                                                                },
                                                                "has_text": {
                                                                    "type": "boolean",
                                                                    "description": "ALWAYS a real answer, in a list as well as on a single campaign. This is the boolean to test \u2014 not `text !== null`."
                                                                },
                                                                "html": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The HTML body. Left out (null) in lists to keep them small: `has_html` says whether there is one. Fetch the campaign on its own to read it."
                                                                },
                                                                "text": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The plain-text body. Left out (null) in lists to keep them small: `has_text` says whether there is one. Fetch the campaign on its own to read it."
                                                                }
                                                            }
                                                        },
                                                        "audience": {
                                                            "type": "object",
                                                            "description": "Static lists plus rule-based segments, minus per-campaign exclusions \u2014 the union-then-subtract the send path materialises.",
                                                            "properties": {
                                                                "lists": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The static lists this campaign sends to, named so you do not have to fetch each one to display it. Null only if the relation was not loaded.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "contact_count": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "How many contacts are on the list. This is not the number of recipients: lists and segments can overlap, and exclusions and suppressed addresses are removed when sending."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "segments": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "The segments this campaign sends to. A segment's members are worked out when the campaign sends, so no count is given.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "includes_unlisted": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the campaign also goes to contacts who are on no list. A campaign can target only these."
                                                                },
                                                                "excluded": {
                                                                    "type": "object",
                                                                    "description": "Contacts held back from this campaign only; their list membership is untouched.",
                                                                    "properties": {
                                                                        "count": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many contacts are excluded. Always present, including in a list response, so you can tell \"none excluded\" from \"not told you\" without fetching the campaign."
                                                                        },
                                                                        "contact_ids": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "description": "`null` in a LIST response means NOT INCLUDED, never \"there are none\" \u2014 the set is unbounded, which is why `count` sits beside it. Fetch the campaign on its own to read the ids."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "schedule": {
                                                            "type": "object",
                                                            "properties": {
                                                                "scheduled_for": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign will go out. Set only while `state` is `scheduled`."
                                                                },
                                                                "started_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the fan-out began. Null until it does \u2014 and that is exactly the cut that makes every count in `/stats` and the whole timeline in `/report` null rather than zero."
                                                                },
                                                                "completed_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the campaign finished sending. Null until then, and for a canceled campaign. Finished sending is not the same as delivered; read `GET /campaigns/{campaign}/stats` for that."
                                                                }
                                                            }
                                                        },
                                                        "resent_from_campaign_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The campaign this one was resent from. Null when it is an original."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "audience": {
                                        "type": "string",
                                        "enum": [
                                            "everyone",
                                            "non_openers",
                                            "failed"
                                        ],
                                        "description": "Who to send it to again: `everyone` it went to, `non_openers` (it reached them but they never opened it), or `failed` (it never reached them).",
                                        "x-example": "non_openers"
                                    }
                                },
                                "required": [
                                    "audience"
                                ]
                            },
                            "example": {
                                "audience": "non_openers"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/campaigns/{campaign}/test-send": {
            "post": {
                "operationId": "postCampaignsCampaignTestSend",
                "summary": "Send a test",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The test send's results. A test does not count as sending the campaign: its state and stats do not change, and the subject is marked as a test. You can test a campaign before marketing review approves your account.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign_test_send"
                                                            ]
                                                        },
                                                        "campaign_id": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "The campaign's lifecycle state, unchanged by the test send \u2014 identical before and after, which is the point of publishing it here."
                                                        },
                                                        "sent": {
                                                            "type": "integer",
                                                            "description": "Results with status `sent`. Derivable, and kept: it is the headline, and it is computed in the same pass as `results` so the two cannot disagree."
                                                        },
                                                        "requested": {
                                                            "type": "integer",
                                                            "description": "Addresses attempted \u2014 at most five."
                                                        },
                                                        "results": {
                                                            "type": "array",
                                                            "description": "One row per address, in the order given.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "email": {
                                                                        "type": "string",
                                                                        "format": "email",
                                                                        "nullable": true,
                                                                        "description": "The address this row is about."
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "sent",
                                                                            "suppressed",
                                                                            "rate_limited",
                                                                            "failed",
                                                                            "unknown"
                                                                        ],
                                                                        "description": "`sent`: handed to the mail server. `suppressed`: on your suppression list. `rate_limited`: over your sending rate. `failed`: see `error`."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "What went wrong, for a person to read. Do not parse it. Null when `status` is `sent`."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Sends the campaign to addresses you name, so you can see it as a recipient would. Does not touch the audience and does not count against the campaign report.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "emails": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 5,
                                        "items": {
                                            "type": "string",
                                            "format": "email"
                                        },
                                        "description": "Where to send the test: 1 to 5 addresses. `{{ tags }}` are filled with sample values.",
                                        "example": [
                                            "you@yourdomain.com"
                                        ],
                                        "x-example": [
                                            "ada@example.com"
                                        ]
                                    }
                                },
                                "required": [
                                    "emails"
                                ]
                            },
                            "example": {
                                "emails": [
                                    "you@yourdomain.com"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/campaigns/{campaign}/preflight": {
            "post": {
                "operationId": "postCampaignsCampaignPreflight",
                "summary": "Preflight a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "Whether the campaign can go out now, and what is stopping it. Readiness depends on your account, the sender, the audience and today's limits, so check it just before sending. Only drafts are checked.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign_preflight"
                                                            ]
                                                        },
                                                        "campaign_id": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "The campaign's lifecycle state, from the same map `campaign.state` uses."
                                                        },
                                                        "sendable": {
                                                            "type": "boolean",
                                                            "description": "The verdict. Exactly `blockers === []`, computed in the same expression, and kept because \"is there anything in this array\" is a worse thing to have to write."
                                                        },
                                                        "blockers": {
                                                            "type": "array",
                                                            "description": "Everything stopping this campaign. Empty means it can be sent. Branch on `code`: `POST /send` and `POST /schedule` give only the message.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "code": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "not_draft",
                                                                            "marketing_review_pending",
                                                                            "sender_unverified",
                                                                            "no_content",
                                                                            "no_unsubscribe",
                                                                            "no_audience",
                                                                            "warmup_exceeded",
                                                                            "marketing_allowance",
                                                                            "scheduled_sends",
                                                                            "bounce_stop",
                                                                            "sample_content"
                                                                        ],
                                                                        "description": "Why the campaign cannot go out.\n\n- `not_draft`: only a draft can be scheduled.\n- `marketing_review_pending`: your account's marketing application is not approved yet.\n- `sender_unverified`: the sender is not verified.\n- `no_content`: no subject and HTML body, and no template.\n- `no_unsubscribe`: the HTML has no unsubscribe link.\n- `no_audience`: no list or segment chosen.\n- `warmup_exceeded`: more recipients than today's warm-up limit allows.\n- `marketing_allowance`: more recipients than your marketing emails left this month. Scheduling answers 402 and names the plan that covers it.\n- `scheduled_sends`: a send time on a plan without scheduling.\n- `bounce_stop`: your marketing is stopped because too many emails bounced; `message` says how to start again.\n- `sample_content`: the email still has a gallery design's sample text, or a link or image to a placeholder address such as example.com; `message` names what to change."
                                                                    },
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "Which part of the campaign the code is about."
                                                                    },
                                                                    "message": {
                                                                        "type": "string",
                                                                        "description": "Human-readable prose. Not stable \u2014 branch on `code`."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "warnings": {
                                                            "type": "array",
                                                            "description": "Worth knowing, does not stop the send.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "code": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "insufficient_credits"
                                                                        ],
                                                                        "description": "`insufficient_credits`: your balance is below the number of recipients. A warning, not a blocker: scheduling still works."
                                                                    },
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "Which part of the campaign the code is about."
                                                                    },
                                                                    "message": {
                                                                        "type": "string",
                                                                        "description": "Human-readable prose. Not stable \u2014 branch on `code`."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "recipient_count": {
                                                            "type": "integer",
                                                            "description": "How many contacts the campaign would go to now, counting each person once and leaving out those who cannot be emailed."
                                                        },
                                                        "credit_balance": {
                                                            "type": "integer",
                                                            "description": "Whole sends, not money: one credit is one recipient. The organization's balance in currency belongs to billing."
                                                        },
                                                        "personalization": {
                                                            "type": "object",
                                                            "properties": {
                                                                "variables": {
                                                                    "type": "array",
                                                                    "description": "Which template variables the content uses. Called `variables`, not `tags`, because this API already uses `tags` for the send-time correlation labels stamped on every message.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "name": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The variable's name, without braces."
                                                                            },
                                                                            "system": {
                                                                                "type": "boolean",
                                                                                "description": "True for variables that always have a value when sending: `email`, `sender_name`, `sender_email`, `organization_name` and `unsubscribe_url`. Their `missing` is always 0. `name` is not one of them, because a contact may have no name."
                                                                            },
                                                                            "missing": {
                                                                                "type": "integer",
                                                                                "description": "Recipients in the audience with no value for it. A count, not a rate \u2014 `recipient_count` is the denominator if you want one."
                                                                            },
                                                                            "default": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The organization's contact-field default, which fills a blank at send time. A variable with a default is never actually empty, so a non-zero `missing` beside a non-null `default` is informational rather than a problem."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "has_unsubscribe": {
                                                                    "type": "boolean",
                                                                    "description": "Whether the content satisfies the compliance gate that `no_unsubscribe` enforces. The blocker is the refusal; this is the observation, and both read the same check."
                                                                }
                                                            }
                                                        },
                                                        "warmup": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Today's warm-up limit for the sending address. Null when your account is not warming up a dedicated IP (most accounts), or when the limit could not be read.",
                                                            "properties": {
                                                                "day": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Which day of the warm-up curve this is. Never null when the enclosing `warmup` object is present \u2014 the snapshot that builds it either has every figure or is itself null."
                                                                },
                                                                "ceiling": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many recipients today's warm-up allows."
                                                                },
                                                                "sent_today": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients already sent from this address today."
                                                                },
                                                                "remaining": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many more recipients today's warm-up allows: `ceiling` minus `sent_today`, never below 0."
                                                                },
                                                                "recipients": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "What THIS campaign would add \u2014 the same projection as the top-level `recipient_count`. Never null when the enclosing `warmup` object is present."
                                                                },
                                                                "completes_on": {
                                                                    "type": "string",
                                                                    "format": "date",
                                                                    "nullable": true,
                                                                    "description": "The date warm-up finishes. Null when it cannot be worked out."
                                                                }
                                                            }
                                                        },
                                                        "unchecked_count": {
                                                            "type": "integer",
                                                            "description": "Recipients whose address was never checked, counted once each, out of `recipient_count`. `POST /campaigns/{id}/check-recipients` checks them, one check each. Always 0 while Bounce protection is off."
                                                        },
                                                        "likely_bad_percent": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Roughly what percent of `recipient_count` looks bad among the unchecked recipients, from a free estimate. Null when there are too few to estimate (under 10), while the estimate is being made, when it cannot be made, or while Bounce protection is off."
                                                        },
                                                        "inbox_full_count": {
                                                            "type": "integer",
                                                            "description": "Recipients whose inbox was full when last checked. Marketing to them is held for 7 days, so the send skips them and uses no credit for them. Counted as of the send time. `recipient_count` still includes them. Always 0 while Bounce protection is off."
                                                        },
                                                        "inbox_full_until": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "The latest time any of the `inbox_full_count` holds ends. `null` when `inbox_full_count` is `0`."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Checks a campaign for the problems that would stop it \u2014 unverified domain, missing\nunsubscribe, empty audience, insufficient allowance \u2014 without sending anything.\n\nOnce Bounce protection is on for your account it also says how many recipients were never\nchecked (`unchecked_count`, and about what share looks bad, `likely_bad_percent`) and how\nmany the send will skip because their inbox is full (`inbox_full_count`, with the latest\nend of those holds in `inbox_full_until`). Skipped recipients are still in\n`recipient_count`; their recipient status reads `skipped_inbox_full`.\n\nIf your marketing is stopped because too many emails bounced, the blocker `bounce_stop`\nsays so, and its `message` says how to start again.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/campaigns/{campaign}/report": {
            "get": {
                "operationId": "getCampaignsCampaignReport",
                "summary": "Report a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign_report"
                                                            ]
                                                        },
                                                        "campaign_id": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "The campaign's lifecycle state, from the same map `campaign.state` uses."
                                                        },
                                                        "timeline": {
                                                            "type": "object",
                                                            "description": "Engagement over time, from the start of sending to the latest event. Null for a campaign that has not started.",
                                                            "properties": {
                                                                "bucket": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "hour",
                                                                        "day"
                                                                    ],
                                                                    "nullable": true,
                                                                    "description": "`hour` while the window is short enough to read that way (72 hours), `day` after. Null when there is no window."
                                                                },
                                                                "points": {
                                                                    "type": "array",
                                                                    "nullable": true,
                                                                    "description": "Null when the campaign never started; never `[]` in that case.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "at": {
                                                                                "type": "string",
                                                                                "format": "date-time",
                                                                                "nullable": true,
                                                                                "description": "The start of the time bucket, in ISO 8601 UTC."
                                                                            },
                                                                            "delivered": {
                                                                                "type": "integer"
                                                                            },
                                                                            "opened": {
                                                                                "type": "integer"
                                                                            },
                                                                            "clicked": {
                                                                                "type": "integer"
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "links": {
                                                            "type": "array",
                                                            "description": "Clicks grouped by DESTINATION, most-clicked first \u2014 a per-destination table, not a list of click events. At most 50 rows; no campaign at today's volumes comes near that. No ratio is published: you have both inputs.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "url": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The link that was clicked. Older clicks whose link was not recorded are grouped as `(unknown link)`."
                                                                    },
                                                                    "total_clicks": {
                                                                        "type": "integer",
                                                                        "description": "Every click on this destination."
                                                                    },
                                                                    "unique_clickers": {
                                                                        "type": "integer",
                                                                        "description": "Distinct recipients who clicked it. Five clicks from one person is not five interested readers, which is why both numbers are kept."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/campaigns/{campaign}/stats": {
            "get": {
                "operationId": "getCampaignsCampaignStats",
                "summary": "Stats a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "Counts for this campaign, each counting people once. Divide them yourself for rates. Opens, clicks, bounces and unsubscribes are matched by address while the campaign is sending, so a person on two campaigns at once can be counted on both.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "campaign_stats"
                                                            ]
                                                        },
                                                        "campaign_id": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "scheduled",
                                                                "sending",
                                                                "paused",
                                                                "sent",
                                                                "canceled",
                                                                "unknown"
                                                            ],
                                                            "description": "The campaign's state, as `state` on the campaign. `sent` means it finished sending, not that the counts below are final."
                                                        },
                                                        "recipients": {
                                                            "type": "object",
                                                            "description": "What happened to each recipient. Every count is null until the campaign starts.",
                                                            "properties": {
                                                                "total": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Every row in the recipient ledger. Null until the campaign starts \u2014 see the group description."
                                                                },
                                                                "pending": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Materialised, not yet attempted. Null until the campaign starts \u2014 see the group description."
                                                                },
                                                                "sent": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients handed to the mail server. Delivery is `engagement.delivered`. Null until the campaign starts."
                                                                },
                                                                "failed": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The send attempt threw. Null until the campaign starts \u2014 see the group description."
                                                                },
                                                                "skipped_suppressed": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "On the organization's suppression list. Null until the campaign starts \u2014 see the group description."
                                                                },
                                                                "skipped_unsubscribed": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Opted out of this organization's mail. Null until the campaign starts \u2014 see the group description."
                                                                }
                                                            }
                                                        },
                                                        "engagement": {
                                                            "type": "object",
                                                            "description": "What came back. Every count is null until the campaign starts.",
                                                            "properties": {
                                                                "delivered": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Confirmations received from the receiving server. Null until the campaign starts \u2014 see the group description."
                                                                },
                                                                "opened": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Unique recipients who opened. Null until the campaign starts \u2014 see the group description."
                                                                },
                                                                "clicked": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Unique recipients who clicked. Null until the campaign starts \u2014 see the group description."
                                                                },
                                                                "bounced": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Unique recipients whose message bounced. Null until the campaign starts \u2014 see the group description."
                                                                },
                                                                "unsubscribed": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Unique recipients who opted out from this message. Null until the campaign starts \u2014 see the group description."
                                                                }
                                                            }
                                                        },
                                                        "generated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When these counts were worked out. They are worked out on every request."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/campaigns/{campaign}/recipients": {
            "get": {
                "operationId": "getCampaignsCampaignRecipients",
                "summary": "Recipients a campaign",
                "tags": [
                    "Campaigns"
                ],
                "x-required-scope": "campaigns:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "The campaign identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Only recipients with this status: `pending`, `sent`, `failed`, `skipped_suppressed`, `skipped_unsubscribed`, `skipped_invalid` (the address does not exist, found before sending) or `skipped_inbox_full` (the inbox was full, so marketing is held for 7 days).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "engagement",
                        "in": "query",
                        "required": false,
                        "description": "`opened`, `not_opened` or `clicked`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Matches the recipient's email.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Page size, 1\u2013100. Default 25.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "campaign_recipient"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "Unique identifier for the recipient row."
                                                                    },
                                                                    "email": {
                                                                        "type": "string",
                                                                        "format": "email"
                                                                    },
                                                                    "contact_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Null for an address that reached the campaign without a contact row behind it."
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "pending",
                                                                            "sent",
                                                                            "failed",
                                                                            "skipped_suppressed",
                                                                            "skipped_unsubscribed",
                                                                            "skipped_invalid",
                                                                            "skipped_inbox_full",
                                                                            "unknown"
                                                                        ],
                                                                        "description": "What happened to this recipient.\n\n- `pending`: not attempted yet.\n- `sent`: handed to the mail server.\n- `failed`: see `error`.\n- `skipped_suppressed`: on your suppression list.\n- `skipped_unsubscribed`: unsubscribed.\n- `skipped_invalid`: the address does not exist, found before sending.\n- `skipped_inbox_full`: the inbox was full, so marketing to this person is held for 7 days."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "What went wrong, for a person to read. Do not parse it. Null when nothing went wrong."
                                                                    },
                                                                    "sent_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the message was handed to the mail server. This is not delivery. Set only when `status` is `sent`; read `status` first."
                                                                    },
                                                                    "opened_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When this recipient first opened the email. Null when no open has been seen."
                                                                    },
                                                                    "clicked_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When this recipient first clicked a link. Null when no click has been seen."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations": {
            "get": {
                "operationId": "getAutomations",
                "summary": "List automations",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "draft",
                                                                            "live",
                                                                            "paused",
                                                                            "archived"
                                                                        ]
                                                                    },
                                                                    "entry_rule": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "once",
                                                                            "every_time",
                                                                            "cooldown"
                                                                        ],
                                                                        "description": "Whether a contact may enter more than once."
                                                                    },
                                                                    "settings": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "exit_events": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                },
                                                                                "description": "Event names that end a run early, checked before every step."
                                                                            },
                                                                            "exits": {
                                                                                "type": "object",
                                                                                "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                                "properties": {
                                                                                    "events": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "properties": {
                                                                                                "event": {
                                                                                                    "type": "string"
                                                                                                },
                                                                                                "where": {
                                                                                                    "type": "array",
                                                                                                    "items": {
                                                                                                        "type": "object",
                                                                                                        "additionalProperties": true
                                                                                                    }
                                                                                                },
                                                                                                "match": {
                                                                                                    "type": "string",
                                                                                                    "enum": [
                                                                                                        "all",
                                                                                                        "any"
                                                                                                    ]
                                                                                                }
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "on_unsubscribe": {
                                                                                        "type": "boolean"
                                                                                    },
                                                                                    "on_reply": {
                                                                                        "type": "boolean",
                                                                                        "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                                    },
                                                                                    "segments_entered": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "string"
                                                                                        }
                                                                                    }
                                                                                }
                                                                            },
                                                                            "stream": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "marketing",
                                                                                    "transactional"
                                                                                ]
                                                                            },
                                                                            "cooldown_hours": {
                                                                                "type": "integer",
                                                                                "nullable": true
                                                                            }
                                                                        }
                                                                    },
                                                                    "graph": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "additionalProperties": true,
                                                                        "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                                    },
                                                                    "validation": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "ok": {
                                                                                "type": "boolean"
                                                                            },
                                                                            "errors": {
                                                                                "type": "object",
                                                                                "additionalProperties": {
                                                                                    "type": "array",
                                                                                    "items": {
                                                                                        "type": "string"
                                                                                    }
                                                                                },
                                                                                "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                            }
                                                                        }
                                                                    },
                                                                    "live_version": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "number": {
                                                                                "type": "integer"
                                                                            },
                                                                            "published_at": {
                                                                                "type": "string",
                                                                                "format": "date-time"
                                                                            }
                                                                        }
                                                                    },
                                                                    "paused_by": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "user",
                                                                            "breaker"
                                                                        ]
                                                                    },
                                                                    "counts": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "in_flight": {
                                                                                "type": "integer",
                                                                                "description": "Runs that have not finished."
                                                                            },
                                                                            "completed": {
                                                                                "type": "integer"
                                                                            },
                                                                            "exited": {
                                                                                "type": "integer"
                                                                            },
                                                                            "failed": {
                                                                                "type": "integer"
                                                                            },
                                                                            "emails_sent": {
                                                                                "type": "integer",
                                                                                "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                            }
                                                                        }
                                                                    },
                                                                    "published_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true
                                                                    },
                                                                    "paused_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true
                                                                    },
                                                                    "archived_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postAutomations",
                "summary": "Create a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "live",
                                                                "paused",
                                                                "archived"
                                                            ]
                                                        },
                                                        "entry_rule": {
                                                            "type": "string",
                                                            "enum": [
                                                                "once",
                                                                "every_time",
                                                                "cooldown"
                                                            ],
                                                            "description": "Whether a contact may enter more than once."
                                                        },
                                                        "settings": {
                                                            "type": "object",
                                                            "properties": {
                                                                "exit_events": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Event names that end a run early, checked before every step."
                                                                },
                                                                "exits": {
                                                                    "type": "object",
                                                                    "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                    "properties": {
                                                                        "events": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "event": {
                                                                                        "type": "string"
                                                                                    },
                                                                                    "where": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "additionalProperties": true
                                                                                        }
                                                                                    },
                                                                                    "match": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "all",
                                                                                            "any"
                                                                                        ]
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "on_unsubscribe": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "on_reply": {
                                                                            "type": "boolean",
                                                                            "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                        },
                                                                        "segments_entered": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "stream": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "marketing",
                                                                        "transactional"
                                                                    ]
                                                                },
                                                                "cooldown_hours": {
                                                                    "type": "integer",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                        },
                                                        "validation": {
                                                            "type": "object",
                                                            "properties": {
                                                                "ok": {
                                                                    "type": "boolean"
                                                                },
                                                                "errors": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                }
                                                            }
                                                        },
                                                        "live_version": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "number": {
                                                                    "type": "integer"
                                                                },
                                                                "published_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                }
                                                            }
                                                        },
                                                        "paused_by": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "user",
                                                                "breaker"
                                                            ]
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "properties": {
                                                                "in_flight": {
                                                                    "type": "integer",
                                                                    "description": "Runs that have not finished."
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                }
                                                            }
                                                        },
                                                        "published_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "paused_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "description": "A name for your team, like `Welcome series`.",
                                        "example": "Welcome series",
                                        "x-example": "Spring newsletter"
                                    },
                                    "recipe": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "description": "Optional. Start from a ready-made automation, by its key from `GET /automations/recipes`."
                                    },
                                    "entry_rule": {
                                        "type": "string",
                                        "enum": [
                                            "once",
                                            "every_time",
                                            "cooldown"
                                        ],
                                        "description": "Whether a contact can go through it more than once: `once` ever, `every_time` the trigger happens, or `cooldown` (again only after `settings.cooldown_hours`).",
                                        "x-example": "once"
                                    },
                                    "graph": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "nodes": {
                                                "type": "array",
                                                "description": "The steps, each `{\"id\", \"type\", \"config\"}`. `GET /automations/node-types` lists the types and what goes in `config`."
                                            },
                                            "edges": {
                                                "type": "array",
                                                "description": "How the steps connect, each `{\"from\", \"to\"}` with step IDs, plus `\"branch\"` after a step that splits."
                                            }
                                        },
                                        "additionalProperties": true,
                                        "description": "The steps, as `{\"nodes\": [...], \"edges\": [...]}`. The easiest way to get a valid one is to build it in the dashboard, or start from a recipe (`GET /automations/recipes`), and read it back with `GET /automations/{id}`. `GET /automations/node-types` lists the step types and their settings."
                                    },
                                    "settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "exit_events": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string",
                                                    "maxLength": 64
                                                },
                                                "description": "Events that take a contact out early, by name, like `order_completed`."
                                            },
                                            "exits": {
                                                "type": "object",
                                                "properties": {
                                                    "events": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "object",
                                                            "properties": {
                                                                "event": {
                                                                    "type": "string",
                                                                    "maxLength": 64,
                                                                    "description": "Which delivery event to pretend happened.",
                                                                    "x-example": "opened"
                                                                },
                                                                "where": {
                                                                    "type": "array",
                                                                    "description": "Optional. Conditions on the event's properties, like a segment's rules."
                                                                },
                                                                "match": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "all",
                                                                        "any"
                                                                    ],
                                                                    "description": "`all` conditions in `where` must match, or `any` one."
                                                                }
                                                            },
                                                            "required": [
                                                                "event"
                                                            ]
                                                        },
                                                        "description": "Events that take a contact out early, each `{\"event\": \"order_completed\"}`, optionally only when the event's properties match `where`."
                                                    },
                                                    "on_unsubscribe": {
                                                        "type": "boolean",
                                                        "description": "Take the contact out when they unsubscribe."
                                                    },
                                                    "on_reply": {
                                                        "type": "boolean",
                                                        "description": "Take the contact out when they reply to one of its emails."
                                                    },
                                                    "segments_entered": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string",
                                                            "maxLength": 64
                                                        },
                                                        "description": "Take the contact out when they join one of these segments, by segment ID."
                                                    }
                                                },
                                                "description": "When a contact leaves early."
                                            },
                                            "goals": {
                                                "type": "array",
                                                "description": "What counts as success, shown in the automation's report."
                                            },
                                            "stream": {
                                                "type": "string",
                                                "enum": [
                                                    "marketing",
                                                    "transactional"
                                                ],
                                                "description": "`transactional` for emails your app sends one at a time, like receipts and sign-in codes; `marketing` for newsletters and promotions. They go out from different addresses so one cannot harm the other.",
                                                "x-example": "transactional"
                                            },
                                            "cooldown_hours": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 8760,
                                                "description": "With `entry_rule: cooldown`: how many hours before a contact may go through again."
                                            }
                                        },
                                        "additionalProperties": true,
                                        "description": "Optional. When contacts leave early (`exit_events`, `exits`), the `goals`, the `stream` (`marketing` or `transactional`) and, for `entry_rule: cooldown`, the `cooldown_hours` between entries. Read the current values with `GET /automations/{id}`."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Welcome series"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/automations/{automation}": {
            "get": {
                "operationId": "getAutomationsAutomation",
                "summary": "Retrieve a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "live",
                                                                "paused",
                                                                "archived"
                                                            ]
                                                        },
                                                        "entry_rule": {
                                                            "type": "string",
                                                            "enum": [
                                                                "once",
                                                                "every_time",
                                                                "cooldown"
                                                            ],
                                                            "description": "Whether a contact may enter more than once."
                                                        },
                                                        "settings": {
                                                            "type": "object",
                                                            "properties": {
                                                                "exit_events": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Event names that end a run early, checked before every step."
                                                                },
                                                                "exits": {
                                                                    "type": "object",
                                                                    "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                    "properties": {
                                                                        "events": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "event": {
                                                                                        "type": "string"
                                                                                    },
                                                                                    "where": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "additionalProperties": true
                                                                                        }
                                                                                    },
                                                                                    "match": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "all",
                                                                                            "any"
                                                                                        ]
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "on_unsubscribe": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "on_reply": {
                                                                            "type": "boolean",
                                                                            "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                        },
                                                                        "segments_entered": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "stream": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "marketing",
                                                                        "transactional"
                                                                    ]
                                                                },
                                                                "cooldown_hours": {
                                                                    "type": "integer",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                        },
                                                        "validation": {
                                                            "type": "object",
                                                            "properties": {
                                                                "ok": {
                                                                    "type": "boolean"
                                                                },
                                                                "errors": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                }
                                                            }
                                                        },
                                                        "live_version": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "number": {
                                                                    "type": "integer"
                                                                },
                                                                "published_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                }
                                                            }
                                                        },
                                                        "paused_by": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "user",
                                                                "breaker"
                                                            ]
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "properties": {
                                                                "in_flight": {
                                                                    "type": "integer",
                                                                    "description": "Runs that have not finished."
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                }
                                                            }
                                                        },
                                                        "published_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "paused_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putAutomationsAutomation",
                "summary": "Update a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "live",
                                                                "paused",
                                                                "archived"
                                                            ]
                                                        },
                                                        "entry_rule": {
                                                            "type": "string",
                                                            "enum": [
                                                                "once",
                                                                "every_time",
                                                                "cooldown"
                                                            ],
                                                            "description": "Whether a contact may enter more than once."
                                                        },
                                                        "settings": {
                                                            "type": "object",
                                                            "properties": {
                                                                "exit_events": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Event names that end a run early, checked before every step."
                                                                },
                                                                "exits": {
                                                                    "type": "object",
                                                                    "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                    "properties": {
                                                                        "events": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "event": {
                                                                                        "type": "string"
                                                                                    },
                                                                                    "where": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "additionalProperties": true
                                                                                        }
                                                                                    },
                                                                                    "match": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "all",
                                                                                            "any"
                                                                                        ]
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "on_unsubscribe": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "on_reply": {
                                                                            "type": "boolean",
                                                                            "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                        },
                                                                        "segments_entered": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "stream": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "marketing",
                                                                        "transactional"
                                                                    ]
                                                                },
                                                                "cooldown_hours": {
                                                                    "type": "integer",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                        },
                                                        "validation": {
                                                            "type": "object",
                                                            "properties": {
                                                                "ok": {
                                                                    "type": "boolean"
                                                                },
                                                                "errors": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                }
                                                            }
                                                        },
                                                        "live_version": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "number": {
                                                                    "type": "integer"
                                                                },
                                                                "published_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                }
                                                            }
                                                        },
                                                        "paused_by": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "user",
                                                                "breaker"
                                                            ]
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "properties": {
                                                                "in_flight": {
                                                                    "type": "integer",
                                                                    "description": "Runs that have not finished."
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                }
                                                            }
                                                        },
                                                        "published_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "paused_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "description": "A name for your team, like `Welcome series`.",
                                        "example": "Welcome series",
                                        "x-example": "Spring newsletter"
                                    },
                                    "entry_rule": {
                                        "type": "string",
                                        "enum": [
                                            "once",
                                            "every_time",
                                            "cooldown"
                                        ],
                                        "description": "Whether a contact can go through it more than once: `once` ever, `every_time` the trigger happens, or `cooldown` (again only after `settings.cooldown_hours`).",
                                        "x-example": "once"
                                    },
                                    "graph": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "nodes": {
                                                "type": "array",
                                                "description": "The steps, each `{\"id\", \"type\", \"config\"}`. `GET /automations/node-types` lists the types and what goes in `config`."
                                            },
                                            "edges": {
                                                "type": "array",
                                                "description": "How the steps connect, each `{\"from\", \"to\"}` with step IDs, plus `\"branch\"` after a step that splits."
                                            }
                                        },
                                        "additionalProperties": true,
                                        "description": "The steps, as `{\"nodes\": [...], \"edges\": [...]}`. The easiest way to get a valid one is to build it in the dashboard, or start from a recipe (`GET /automations/recipes`), and read it back with `GET /automations/{id}`. `GET /automations/node-types` lists the step types and their settings."
                                    },
                                    "settings": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "exit_events": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string",
                                                    "maxLength": 64
                                                },
                                                "description": "Events that take a contact out early, by name, like `order_completed`."
                                            },
                                            "exits": {
                                                "type": "object",
                                                "properties": {
                                                    "events": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "object",
                                                            "properties": {
                                                                "event": {
                                                                    "type": "string",
                                                                    "maxLength": 64,
                                                                    "description": "Which delivery event to pretend happened.",
                                                                    "x-example": "opened"
                                                                },
                                                                "where": {
                                                                    "type": "array",
                                                                    "description": "Optional. Conditions on the event's properties, like a segment's rules."
                                                                },
                                                                "match": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "all",
                                                                        "any"
                                                                    ],
                                                                    "description": "`all` conditions in `where` must match, or `any` one."
                                                                }
                                                            },
                                                            "required": [
                                                                "event"
                                                            ]
                                                        },
                                                        "description": "Events that take a contact out early, each `{\"event\": \"order_completed\"}`, optionally only when the event's properties match `where`."
                                                    },
                                                    "on_unsubscribe": {
                                                        "type": "boolean",
                                                        "description": "Take the contact out when they unsubscribe."
                                                    },
                                                    "on_reply": {
                                                        "type": "boolean",
                                                        "description": "Take the contact out when they reply to one of its emails."
                                                    },
                                                    "segments_entered": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string",
                                                            "maxLength": 64
                                                        },
                                                        "description": "Take the contact out when they join one of these segments, by segment ID."
                                                    }
                                                },
                                                "description": "When a contact leaves early."
                                            },
                                            "goals": {
                                                "type": "array",
                                                "description": "What counts as success, shown in the automation's report."
                                            },
                                            "stream": {
                                                "type": "string",
                                                "enum": [
                                                    "marketing",
                                                    "transactional"
                                                ],
                                                "description": "`transactional` for emails your app sends one at a time, like receipts and sign-in codes; `marketing` for newsletters and promotions. They go out from different addresses so one cannot harm the other.",
                                                "x-example": "transactional"
                                            },
                                            "cooldown_hours": {
                                                "nullable": true,
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 8760,
                                                "description": "With `entry_rule: cooldown`: how many hours before a contact may go through again."
                                            }
                                        },
                                        "additionalProperties": true,
                                        "description": "Optional. When contacts leave early (`exit_events`, `exits`), the `goals`, the `stream` (`marketing` or `transactional`) and, for `entry_rule: cooldown`, the `cooldown_hours` between entries. Read the current values with `GET /automations/{id}`."
                                    }
                                }
                            },
                            "example": {
                                "name": "Welcome series"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteAutomationsAutomation",
                "summary": "Delete a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. Only a draft can be deleted; archive a live or paused automation instead."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/{automation}/publish": {
            "post": {
                "operationId": "postAutomationsAutomationPublish",
                "summary": "Publish an automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "live",
                                                                "paused",
                                                                "archived"
                                                            ]
                                                        },
                                                        "entry_rule": {
                                                            "type": "string",
                                                            "enum": [
                                                                "once",
                                                                "every_time",
                                                                "cooldown"
                                                            ],
                                                            "description": "Whether a contact may enter more than once."
                                                        },
                                                        "settings": {
                                                            "type": "object",
                                                            "properties": {
                                                                "exit_events": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Event names that end a run early, checked before every step."
                                                                },
                                                                "exits": {
                                                                    "type": "object",
                                                                    "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                    "properties": {
                                                                        "events": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "event": {
                                                                                        "type": "string"
                                                                                    },
                                                                                    "where": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "additionalProperties": true
                                                                                        }
                                                                                    },
                                                                                    "match": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "all",
                                                                                            "any"
                                                                                        ]
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "on_unsubscribe": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "on_reply": {
                                                                            "type": "boolean",
                                                                            "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                        },
                                                                        "segments_entered": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "stream": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "marketing",
                                                                        "transactional"
                                                                    ]
                                                                },
                                                                "cooldown_hours": {
                                                                    "type": "integer",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                        },
                                                        "validation": {
                                                            "type": "object",
                                                            "properties": {
                                                                "ok": {
                                                                    "type": "boolean"
                                                                },
                                                                "errors": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                }
                                                            }
                                                        },
                                                        "live_version": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "number": {
                                                                    "type": "integer"
                                                                },
                                                                "published_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                }
                                                            }
                                                        },
                                                        "paused_by": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "user",
                                                                "breaker"
                                                            ]
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "properties": {
                                                                "in_flight": {
                                                                    "type": "integer",
                                                                    "description": "Runs that have not finished."
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                }
                                                            }
                                                        },
                                                        "published_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "paused_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Validates the draft and, when it passes, makes it the live version. People already inside finish the version they entered; new entrants get this one. A draft with problems answers `422` naming them.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/automations/{automation}/pause": {
            "post": {
                "operationId": "postAutomationsAutomationPause",
                "summary": "Pause an automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "live",
                                                                "paused",
                                                                "archived"
                                                            ]
                                                        },
                                                        "entry_rule": {
                                                            "type": "string",
                                                            "enum": [
                                                                "once",
                                                                "every_time",
                                                                "cooldown"
                                                            ],
                                                            "description": "Whether a contact may enter more than once."
                                                        },
                                                        "settings": {
                                                            "type": "object",
                                                            "properties": {
                                                                "exit_events": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Event names that end a run early, checked before every step."
                                                                },
                                                                "exits": {
                                                                    "type": "object",
                                                                    "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                    "properties": {
                                                                        "events": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "event": {
                                                                                        "type": "string"
                                                                                    },
                                                                                    "where": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "additionalProperties": true
                                                                                        }
                                                                                    },
                                                                                    "match": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "all",
                                                                                            "any"
                                                                                        ]
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "on_unsubscribe": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "on_reply": {
                                                                            "type": "boolean",
                                                                            "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                        },
                                                                        "segments_entered": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "stream": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "marketing",
                                                                        "transactional"
                                                                    ]
                                                                },
                                                                "cooldown_hours": {
                                                                    "type": "integer",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                        },
                                                        "validation": {
                                                            "type": "object",
                                                            "properties": {
                                                                "ok": {
                                                                    "type": "boolean"
                                                                },
                                                                "errors": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                }
                                                            }
                                                        },
                                                        "live_version": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "number": {
                                                                    "type": "integer"
                                                                },
                                                                "published_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                }
                                                            }
                                                        },
                                                        "paused_by": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "user",
                                                                "breaker"
                                                            ]
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "properties": {
                                                                "in_flight": {
                                                                    "type": "integer",
                                                                    "description": "Runs that have not finished."
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                }
                                                            }
                                                        },
                                                        "published_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "paused_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Stops a live automation. Nobody new enters and nobody inside moves; resuming carries on where each person was, and waits that fell due meanwhile run straight away.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/automations/{automation}/resume": {
            "post": {
                "operationId": "postAutomationsAutomationResume",
                "summary": "Resume an automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "live",
                                                                "paused",
                                                                "archived"
                                                            ]
                                                        },
                                                        "entry_rule": {
                                                            "type": "string",
                                                            "enum": [
                                                                "once",
                                                                "every_time",
                                                                "cooldown"
                                                            ],
                                                            "description": "Whether a contact may enter more than once."
                                                        },
                                                        "settings": {
                                                            "type": "object",
                                                            "properties": {
                                                                "exit_events": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Event names that end a run early, checked before every step."
                                                                },
                                                                "exits": {
                                                                    "type": "object",
                                                                    "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                    "properties": {
                                                                        "events": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "event": {
                                                                                        "type": "string"
                                                                                    },
                                                                                    "where": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "additionalProperties": true
                                                                                        }
                                                                                    },
                                                                                    "match": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "all",
                                                                                            "any"
                                                                                        ]
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "on_unsubscribe": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "on_reply": {
                                                                            "type": "boolean",
                                                                            "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                        },
                                                                        "segments_entered": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "stream": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "marketing",
                                                                        "transactional"
                                                                    ]
                                                                },
                                                                "cooldown_hours": {
                                                                    "type": "integer",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                        },
                                                        "validation": {
                                                            "type": "object",
                                                            "properties": {
                                                                "ok": {
                                                                    "type": "boolean"
                                                                },
                                                                "errors": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                }
                                                            }
                                                        },
                                                        "live_version": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "number": {
                                                                    "type": "integer"
                                                                },
                                                                "published_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                }
                                                            }
                                                        },
                                                        "paused_by": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "user",
                                                                "breaker"
                                                            ]
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "properties": {
                                                                "in_flight": {
                                                                    "type": "integer",
                                                                    "description": "Runs that have not finished."
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                }
                                                            }
                                                        },
                                                        "published_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "paused_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Restarts a paused automation. Refused with `422` when Mailyte paused it for unusual sending volume; that needs support.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/automations/{automation}/archive": {
            "post": {
                "operationId": "postAutomationsAutomationArchive",
                "summary": "Archive an automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "live",
                                                                "paused",
                                                                "archived"
                                                            ]
                                                        },
                                                        "entry_rule": {
                                                            "type": "string",
                                                            "enum": [
                                                                "once",
                                                                "every_time",
                                                                "cooldown"
                                                            ],
                                                            "description": "Whether a contact may enter more than once."
                                                        },
                                                        "settings": {
                                                            "type": "object",
                                                            "properties": {
                                                                "exit_events": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Event names that end a run early, checked before every step."
                                                                },
                                                                "exits": {
                                                                    "type": "object",
                                                                    "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                    "properties": {
                                                                        "events": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "event": {
                                                                                        "type": "string"
                                                                                    },
                                                                                    "where": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "additionalProperties": true
                                                                                        }
                                                                                    },
                                                                                    "match": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "all",
                                                                                            "any"
                                                                                        ]
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "on_unsubscribe": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "on_reply": {
                                                                            "type": "boolean",
                                                                            "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                        },
                                                                        "segments_entered": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "stream": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "marketing",
                                                                        "transactional"
                                                                    ]
                                                                },
                                                                "cooldown_hours": {
                                                                    "type": "integer",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                        },
                                                        "validation": {
                                                            "type": "object",
                                                            "properties": {
                                                                "ok": {
                                                                    "type": "boolean"
                                                                },
                                                                "errors": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                }
                                                            }
                                                        },
                                                        "live_version": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "number": {
                                                                    "type": "integer"
                                                                },
                                                                "published_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                }
                                                            }
                                                        },
                                                        "paused_by": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "user",
                                                                "breaker"
                                                            ]
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "properties": {
                                                                "in_flight": {
                                                                    "type": "integer",
                                                                    "description": "Runs that have not finished."
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                }
                                                            }
                                                        },
                                                        "published_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "paused_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Stops an automation for good. Everyone inside leaves it and it cannot be published again; its history stays readable.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/automations/{automation}/enrol": {
            "post": {
                "operationId": "postAutomationsAutomationEnrol",
                "summary": "Enrol a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "automation_id": {
                                                            "type": "string"
                                                        },
                                                        "version_id": {
                                                            "type": "string",
                                                            "description": "The version this run entered. It finishes that version even if a newer one is published."
                                                        },
                                                        "version_number": {
                                                            "type": "integer",
                                                            "nullable": true
                                                        },
                                                        "contact": {
                                                            "type": "object",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "email": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "enrolled",
                                                                "running",
                                                                "waiting_time",
                                                                "waiting_event",
                                                                "paused",
                                                                "completed",
                                                                "exited",
                                                                "failed"
                                                            ]
                                                        },
                                                        "current_node_id": {
                                                            "type": "string"
                                                        },
                                                        "wake_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the engine next picks this run up. UTC."
                                                        },
                                                        "waiting_event": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "entered_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "ended_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "exit_reason": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Why the run ended early: event:<name>, unsubscribed, archived, goal:<node>."
                                                        },
                                                        "error": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "context": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The trigger payload: the event properties, or the list or tag that started the run."
                                                        },
                                                        "automation": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string"
                                                                },
                                                                "state": {
                                                                    "type": "string"
                                                                }
                                                            },
                                                            "description": "Present on a contact's run list."
                                                        },
                                                        "summary": {
                                                            "type": "string",
                                                            "description": "One plain-language line about this run. Present on a contact's run list."
                                                        },
                                                        "steps": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "integer"
                                                                    },
                                                                    "node_id": {
                                                                        "type": "string",
                                                                        "description": "The node in the version graph this step belongs to."
                                                                    },
                                                                    "node_type": {
                                                                        "type": "string",
                                                                        "description": "The node type, e.g. delay, send_email, trigger, exit_rule."
                                                                    },
                                                                    "occurred_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "outcome": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "enrolled",
                                                                            "executed",
                                                                            "sending",
                                                                            "sent",
                                                                            "skipped",
                                                                            "deferred",
                                                                            "branch",
                                                                            "exited",
                                                                            "failed",
                                                                            "unknown"
                                                                        ]
                                                                    },
                                                                    "branch_taken": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The sent message, when this step sent one. Ties the step to delivery events."
                                                                    },
                                                                    "skipped_reason": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why nothing was sent: `suppressed`, `unsubscribed`, `marketing_review_pending`, `rate_limited`, `not_mailable` or `inbox_full`. With `inbox_full`, marketing to this person is held until `details.email_full_until`."
                                                                    },
                                                                    "details": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "additionalProperties": true
                                                                    }
                                                                }
                                                            },
                                                            "description": "Present when a single run is fetched; omitted from the list."
                                                        },
                                                        "narrative": {
                                                            "type": "object",
                                                            "description": "Present when a single run is fetched: the steps as sentences, in the contact's local time.",
                                                            "properties": {
                                                                "timezone": {
                                                                    "type": "string"
                                                                },
                                                                "tz_source": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "contact",
                                                                        "organization_default",
                                                                        "utc"
                                                                    ],
                                                                    "description": "Where the timezone came from: the contact's own attribute, the organisation default, or UTC."
                                                                },
                                                                "paragraphs": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "One paragraph per local day, plus what never happened after an early exit."
                                                                },
                                                                "lines": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "node_id": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            },
                                                                            "at": {
                                                                                "type": "string",
                                                                                "format": "date-time",
                                                                                "nullable": true
                                                                            },
                                                                            "text": {
                                                                                "type": "string"
                                                                            },
                                                                            "outcome": {
                                                                                "type": "string"
                                                                            },
                                                                            "ghost": {
                                                                                "type": "boolean",
                                                                                "description": "True for a step that never ran because the run ended early."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "contact_id": {
                                        "type": "string",
                                        "description": "The contact to put in, by ID. Send this or `email`.",
                                        "example": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Or the email address of a contact you already have."
                                    }
                                }
                            },
                            "example": {
                                "contact_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/automations/{automation}/versions": {
            "get": {
                "operationId": "getAutomationsAutomationVersions",
                "summary": "Versions a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string"
                                                            },
                                                            "automation_id": {
                                                                "type": "string"
                                                            },
                                                            "number": {
                                                                "type": "integer"
                                                            },
                                                            "graph": {
                                                                "type": "object",
                                                                "additionalProperties": true,
                                                                "description": "The immutable graph: {nodes[], edges[], settings}."
                                                            },
                                                            "published_at": {
                                                                "type": "string",
                                                                "format": "date-time"
                                                            },
                                                            "published_by": {
                                                                "type": "string",
                                                                "nullable": true
                                                            },
                                                            "is_live": {
                                                                "type": "boolean"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/{automation}/runs": {
            "get": {
                "operationId": "getAutomationsAutomationRuns",
                "summary": "Runs a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "automation_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "version_id": {
                                                                        "type": "string",
                                                                        "description": "The version this run entered. It finishes that version even if a newer one is published."
                                                                    },
                                                                    "version_number": {
                                                                        "type": "integer",
                                                                        "nullable": true
                                                                    },
                                                                    "contact": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "email": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            }
                                                                        }
                                                                    },
                                                                    "state": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "enrolled",
                                                                            "running",
                                                                            "waiting_time",
                                                                            "waiting_event",
                                                                            "paused",
                                                                            "completed",
                                                                            "exited",
                                                                            "failed"
                                                                        ]
                                                                    },
                                                                    "current_node_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "wake_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the engine next picks this run up. UTC."
                                                                    },
                                                                    "waiting_event": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "entered_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "ended_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true
                                                                    },
                                                                    "exit_reason": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why the run ended early: event:<name>, unsubscribed, archived, goal:<node>."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "context": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "additionalProperties": true,
                                                                        "description": "The trigger payload: the event properties, or the list or tag that started the run."
                                                                    },
                                                                    "automation": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "state": {
                                                                                "type": "string"
                                                                            }
                                                                        },
                                                                        "description": "Present on a contact's run list."
                                                                    },
                                                                    "summary": {
                                                                        "type": "string",
                                                                        "description": "One plain-language line about this run. Present on a contact's run list."
                                                                    },
                                                                    "steps": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "id": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "node_id": {
                                                                                    "type": "string",
                                                                                    "description": "The node in the version graph this step belongs to."
                                                                                },
                                                                                "node_type": {
                                                                                    "type": "string",
                                                                                    "description": "The node type, e.g. delay, send_email, trigger, exit_rule."
                                                                                },
                                                                                "occurred_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "outcome": {
                                                                                    "type": "string",
                                                                                    "enum": [
                                                                                        "enrolled",
                                                                                        "executed",
                                                                                        "sending",
                                                                                        "sent",
                                                                                        "skipped",
                                                                                        "deferred",
                                                                                        "branch",
                                                                                        "exited",
                                                                                        "failed",
                                                                                        "unknown"
                                                                                    ]
                                                                                },
                                                                                "branch_taken": {
                                                                                    "type": "string",
                                                                                    "nullable": true
                                                                                },
                                                                                "message_id": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "description": "The sent message, when this step sent one. Ties the step to delivery events."
                                                                                },
                                                                                "skipped_reason": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "description": "Why nothing was sent: `suppressed`, `unsubscribed`, `marketing_review_pending`, `rate_limited`, `not_mailable` or `inbox_full`. With `inbox_full`, marketing to this person is held until `details.email_full_until`."
                                                                                },
                                                                                "details": {
                                                                                    "type": "object",
                                                                                    "nullable": true,
                                                                                    "additionalProperties": true
                                                                                }
                                                                            }
                                                                        },
                                                                        "description": "Present when a single run is fetched; omitted from the list."
                                                                    },
                                                                    "narrative": {
                                                                        "type": "object",
                                                                        "description": "Present when a single run is fetched: the steps as sentences, in the contact's local time.",
                                                                        "properties": {
                                                                            "timezone": {
                                                                                "type": "string"
                                                                            },
                                                                            "tz_source": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "contact",
                                                                                    "organization_default",
                                                                                    "utc"
                                                                                ],
                                                                                "description": "Where the timezone came from: the contact's own attribute, the organisation default, or UTC."
                                                                            },
                                                                            "paragraphs": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                },
                                                                                "description": "One paragraph per local day, plus what never happened after an early exit."
                                                                            },
                                                                            "lines": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "object",
                                                                                    "properties": {
                                                                                        "node_id": {
                                                                                            "type": "string",
                                                                                            "nullable": true
                                                                                        },
                                                                                        "at": {
                                                                                            "type": "string",
                                                                                            "format": "date-time",
                                                                                            "nullable": true
                                                                                        },
                                                                                        "text": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "outcome": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "ghost": {
                                                                                            "type": "boolean",
                                                                                            "description": "True for a step that never ran because the run ended early."
                                                                                        }
                                                                                    }
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/{automation}/runs/{run}": {
            "get": {
                "operationId": "getAutomationsAutomationRunsRun",
                "summary": "Retrieve a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "run",
                        "in": "path",
                        "required": true,
                        "description": "The run identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "automation_id": {
                                                            "type": "string"
                                                        },
                                                        "version_id": {
                                                            "type": "string",
                                                            "description": "The version this run entered. It finishes that version even if a newer one is published."
                                                        },
                                                        "version_number": {
                                                            "type": "integer",
                                                            "nullable": true
                                                        },
                                                        "contact": {
                                                            "type": "object",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "email": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "enrolled",
                                                                "running",
                                                                "waiting_time",
                                                                "waiting_event",
                                                                "paused",
                                                                "completed",
                                                                "exited",
                                                                "failed"
                                                            ]
                                                        },
                                                        "current_node_id": {
                                                            "type": "string"
                                                        },
                                                        "wake_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the engine next picks this run up. UTC."
                                                        },
                                                        "waiting_event": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "entered_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "ended_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "exit_reason": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Why the run ended early: event:<name>, unsubscribed, archived, goal:<node>."
                                                        },
                                                        "error": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "context": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The trigger payload: the event properties, or the list or tag that started the run."
                                                        },
                                                        "automation": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": "string"
                                                                },
                                                                "state": {
                                                                    "type": "string"
                                                                }
                                                            },
                                                            "description": "Present on a contact's run list."
                                                        },
                                                        "summary": {
                                                            "type": "string",
                                                            "description": "One plain-language line about this run. Present on a contact's run list."
                                                        },
                                                        "steps": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "integer"
                                                                    },
                                                                    "node_id": {
                                                                        "type": "string",
                                                                        "description": "The node in the version graph this step belongs to."
                                                                    },
                                                                    "node_type": {
                                                                        "type": "string",
                                                                        "description": "The node type, e.g. delay, send_email, trigger, exit_rule."
                                                                    },
                                                                    "occurred_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "outcome": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "enrolled",
                                                                            "executed",
                                                                            "sending",
                                                                            "sent",
                                                                            "skipped",
                                                                            "deferred",
                                                                            "branch",
                                                                            "exited",
                                                                            "failed",
                                                                            "unknown"
                                                                        ]
                                                                    },
                                                                    "branch_taken": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The sent message, when this step sent one. Ties the step to delivery events."
                                                                    },
                                                                    "skipped_reason": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why nothing was sent: `suppressed`, `unsubscribed`, `marketing_review_pending`, `rate_limited`, `not_mailable` or `inbox_full`. With `inbox_full`, marketing to this person is held until `details.email_full_until`."
                                                                    },
                                                                    "details": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "additionalProperties": true
                                                                    }
                                                                }
                                                            },
                                                            "description": "Present when a single run is fetched; omitted from the list."
                                                        },
                                                        "narrative": {
                                                            "type": "object",
                                                            "description": "Present when a single run is fetched: the steps as sentences, in the contact's local time.",
                                                            "properties": {
                                                                "timezone": {
                                                                    "type": "string"
                                                                },
                                                                "tz_source": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "contact",
                                                                        "organization_default",
                                                                        "utc"
                                                                    ],
                                                                    "description": "Where the timezone came from: the contact's own attribute, the organisation default, or UTC."
                                                                },
                                                                "paragraphs": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "One paragraph per local day, plus what never happened after an early exit."
                                                                },
                                                                "lines": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "node_id": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            },
                                                                            "at": {
                                                                                "type": "string",
                                                                                "format": "date-time",
                                                                                "nullable": true
                                                                            },
                                                                            "text": {
                                                                                "type": "string"
                                                                            },
                                                                            "outcome": {
                                                                                "type": "string"
                                                                            },
                                                                            "ghost": {
                                                                                "type": "boolean",
                                                                                "description": "True for a step that never ran because the run ended early."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/node-types": {
            "get": {
                "operationId": "getAutomationsNodeTypes",
                "summary": "Node Types (automation)",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "type": {
                                                                "type": "string",
                                                                "description": "The value to put in a node's type, e.g. trigger.event, delay, send_email."
                                                            },
                                                            "label": {
                                                                "type": "string"
                                                            },
                                                            "group": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "trigger",
                                                                    "action",
                                                                    "logic"
                                                                ]
                                                            },
                                                            "boundary": {
                                                                "type": "boolean",
                                                                "description": "True when the engine stops after this node (a wait or a send)."
                                                            },
                                                            "config": {
                                                                "type": "object",
                                                                "additionalProperties": true,
                                                                "description": "What the node's config accepts: {field: {type, required, description}}."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/recipes": {
            "get": {
                "operationId": "getAutomationsRecipes",
                "summary": "Recipes (automation)",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "key": {
                                                                "type": "string"
                                                            },
                                                            "name": {
                                                                "type": "string"
                                                            },
                                                            "description": {
                                                                "type": "string"
                                                            },
                                                            "category": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "welcome",
                                                                    "recovery",
                                                                    "loyalty",
                                                                    "reengagement",
                                                                    "milestones",
                                                                    "nurture",
                                                                    "other"
                                                                ]
                                                            },
                                                            "phase": {
                                                                "type": "integer"
                                                            },
                                                            "entry_rule": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "once",
                                                                    "every_time",
                                                                    "cooldown"
                                                                ]
                                                            },
                                                            "cooldown_hours": {
                                                                "type": "integer",
                                                                "nullable": true
                                                            },
                                                            "placeholders": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "string"
                                                                },
                                                                "description": "Node ids the customer must complete before publishing."
                                                            },
                                                            "graph": {
                                                                "type": "object",
                                                                "additionalProperties": true
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/settings": {
            "get": {
                "operationId": "getAutomationsSettings",
                "summary": "Settings (automation)",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "max_marketing_per_day": {
                                                            "type": "integer",
                                                            "description": "Marketing emails one contact may receive per local calendar day, across automations and campaigns. Default 2."
                                                        },
                                                        "max_marketing_per_week": {
                                                            "type": "integer",
                                                            "description": "Same, per trailing seven local days. Default 6."
                                                        },
                                                        "quiet_hours_enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "quiet_hours_start": {
                                                            "type": "string",
                                                            "example": "21:00",
                                                            "description": "HH:MM in the contact's local time. Automated sends inside quiet hours are held, never dropped."
                                                        },
                                                        "quiet_hours_end": {
                                                            "type": "string",
                                                            "example": "08:00"
                                                        },
                                                        "send_window_days": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "integer",
                                                                "minimum": 1,
                                                                "maximum": 7
                                                            },
                                                            "description": "ISO weekdays automated mail may go out on: 1 = Monday \u2026 7 = Sunday."
                                                        },
                                                        "default_timezone": {
                                                            "type": "string",
                                                            "example": "Africa/Lagos",
                                                            "description": "Used for a contact with no timezone attribute of their own."
                                                        },
                                                        "pause_on_reply_days": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Reserved: pause a contact's journeys for this many days after they reply."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putAutomationsSettings",
                "summary": "Settings (automation)",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "max_marketing_per_day": {
                                                            "type": "integer",
                                                            "description": "Marketing emails one contact may receive per local calendar day, across automations and campaigns. Default 2."
                                                        },
                                                        "max_marketing_per_week": {
                                                            "type": "integer",
                                                            "description": "Same, per trailing seven local days. Default 6."
                                                        },
                                                        "quiet_hours_enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "quiet_hours_start": {
                                                            "type": "string",
                                                            "example": "21:00",
                                                            "description": "HH:MM in the contact's local time. Automated sends inside quiet hours are held, never dropped."
                                                        },
                                                        "quiet_hours_end": {
                                                            "type": "string",
                                                            "example": "08:00"
                                                        },
                                                        "send_window_days": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "integer",
                                                                "minimum": 1,
                                                                "maximum": 7
                                                            },
                                                            "description": "ISO weekdays automated mail may go out on: 1 = Monday \u2026 7 = Sunday."
                                                        },
                                                        "default_timezone": {
                                                            "type": "string",
                                                            "example": "Africa/Lagos",
                                                            "description": "Used for a contact with no timezone attribute of their own."
                                                        },
                                                        "pause_on_reply_days": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Reserved: pause a contact's journeys for this many days after they reply."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "max_marketing_per_day": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 50,
                                        "description": "The most automated marketing emails one contact may get in a day.",
                                        "x-example": 2
                                    },
                                    "max_marketing_per_week": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 200,
                                        "description": "The most automated marketing emails one contact may get in a week.",
                                        "x-example": 5
                                    },
                                    "quiet_hours_enabled": {
                                        "type": "boolean",
                                        "description": "Hold automated emails during quiet hours. They are sent when quiet hours end, never dropped.",
                                        "x-example": true
                                    },
                                    "quiet_hours_start": {
                                        "type": "string",
                                        "description": "When quiet hours begin, as `HH:MM` like `21:00`, in the contact's own time.",
                                        "x-example": "21:00"
                                    },
                                    "quiet_hours_end": {
                                        "type": "string",
                                        "description": "When quiet hours end, as `HH:MM` like `08:00`.",
                                        "x-example": "08:00"
                                    },
                                    "send_window_days": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 7,
                                        "items": {
                                            "type": "integer",
                                            "minimum": 1,
                                            "maximum": 7
                                        },
                                        "description": "The days automated emails may go out, as numbers: 1 = Monday \u2026 7 = Sunday.",
                                        "x-example": [
                                            1,
                                            2,
                                            3,
                                            4,
                                            5
                                        ]
                                    },
                                    "default_timezone": {
                                        "type": "string",
                                        "description": "The timezone used for a contact with no timezone of their own, as an IANA name like `Africa/Lagos`.",
                                        "x-example": "Africa/Lagos"
                                    },
                                    "pause_on_reply_days": {
                                        "nullable": true,
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 90,
                                        "description": "Reserved for pausing a contact's automations after they reply. Saved, but not acted on yet."
                                    }
                                }
                            },
                            "example": {
                                "max_marketing_per_day": 2,
                                "max_marketing_per_week": 5
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/automations/{automation}/report": {
            "get": {
                "operationId": "getAutomationsAutomationReport",
                "summary": "Report a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "automation_id": {
                                                            "type": "string"
                                                        },
                                                        "version_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Per-node counters and engagement belong to the live version."
                                                        },
                                                        "attribution_window_days": {
                                                            "type": "integer",
                                                            "description": "A conversion is attributed to the last email sent within this many days before the goal."
                                                        },
                                                        "totals": {
                                                            "type": "object",
                                                            "properties": {
                                                                "entered": {
                                                                    "type": "integer"
                                                                },
                                                                "in_flight": {
                                                                    "type": "integer"
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "converted": {
                                                                    "type": "integer"
                                                                },
                                                                "conversion_rate": {
                                                                    "type": "number",
                                                                    "nullable": true,
                                                                    "description": "Percentage, null when there is no denominator."
                                                                },
                                                                "exits_by_reason": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "integer"
                                                                    },
                                                                    "description": "goal, exit_event, segment, unsubscribed, archived, or the raw reason."
                                                                }
                                                            }
                                                        },
                                                        "nodes": {
                                                            "type": "array",
                                                            "description": "In the tree's order from the trigger.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "node_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "type": {
                                                                        "type": "string"
                                                                    },
                                                                    "label": {
                                                                        "type": "string"
                                                                    },
                                                                    "entered": {
                                                                        "type": "integer"
                                                                    },
                                                                    "completed": {
                                                                        "type": "integer"
                                                                    },
                                                                    "skipped": {
                                                                        "type": "integer"
                                                                    },
                                                                    "converted": {
                                                                        "type": "integer"
                                                                    },
                                                                    "in_flight": {
                                                                        "type": "integer"
                                                                    },
                                                                    "sent": {
                                                                        "type": "integer",
                                                                        "description": "send_email nodes only."
                                                                    },
                                                                    "delivered": {
                                                                        "type": "integer"
                                                                    },
                                                                    "opened": {
                                                                        "type": "integer"
                                                                    },
                                                                    "clicked": {
                                                                        "type": "integer"
                                                                    },
                                                                    "open_rate": {
                                                                        "type": "number",
                                                                        "nullable": true,
                                                                        "description": "Percentage, null when there is no denominator."
                                                                    },
                                                                    "click_rate": {
                                                                        "type": "number",
                                                                        "nullable": true,
                                                                        "description": "Percentage, null when there is no denominator."
                                                                    },
                                                                    "attributed_conversions": {
                                                                        "type": "integer",
                                                                        "description": "Goals reached within the window after this email."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/{automation}/experiments": {
            "get": {
                "operationId": "getAutomationsAutomationExperiments",
                "summary": "Experiments a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "automation_id": {
                                                            "type": "string"
                                                        },
                                                        "version_id": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "experiments": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "node_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "metric": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "clicked",
                                                                            "opened",
                                                                            "converted"
                                                                        ]
                                                                    },
                                                                    "promoted": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The winning variant key once promoted."
                                                                    },
                                                                    "variants": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "key": {
                                                                                    "type": "string"
                                                                                },
                                                                                "label": {
                                                                                    "type": "string"
                                                                                },
                                                                                "percent": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "entered": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "sent": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "delivered": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "opened": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "clicked": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "converted": {
                                                                                    "type": "integer"
                                                                                },
                                                                                "rate": {
                                                                                    "type": "number",
                                                                                    "nullable": true,
                                                                                    "description": "The metric as a percentage."
                                                                                }
                                                                            }
                                                                        }
                                                                    },
                                                                    "verdict": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "status": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "winner",
                                                                                    "not_enough_data",
                                                                                    "no_difference"
                                                                                ]
                                                                            },
                                                                            "leader": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            },
                                                                            "confidence": {
                                                                                "type": "number",
                                                                                "nullable": true,
                                                                                "description": "Two-sided confidence from a two-proportion z-test, 0\u20131."
                                                                            },
                                                                            "message": {
                                                                                "type": "string",
                                                                                "description": "The verdict in plain words."
                                                                            },
                                                                            "needed_more": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "Roughly how many more sends per variant would settle it."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/{automation}/experiments/{node}/promote": {
            "post": {
                "operationId": "postAutomationsAutomationExperimentsNodePromote",
                "summary": "Promote a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "node",
                        "in": "path",
                        "required": true,
                        "description": "The node identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "draft",
                                                                "live",
                                                                "paused",
                                                                "archived"
                                                            ]
                                                        },
                                                        "entry_rule": {
                                                            "type": "string",
                                                            "enum": [
                                                                "once",
                                                                "every_time",
                                                                "cooldown"
                                                            ],
                                                            "description": "Whether a contact may enter more than once."
                                                        },
                                                        "settings": {
                                                            "type": "object",
                                                            "properties": {
                                                                "exit_events": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Event names that end a run early, checked before every step."
                                                                },
                                                                "exits": {
                                                                    "type": "object",
                                                                    "description": "The full exit rules: events (with optional property filters), whether unsubscribing exits, and segments whose entry exits.",
                                                                    "properties": {
                                                                        "events": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "event": {
                                                                                        "type": "string"
                                                                                    },
                                                                                    "where": {
                                                                                        "type": "array",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "additionalProperties": true
                                                                                        }
                                                                                    },
                                                                                    "match": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "all",
                                                                                            "any"
                                                                                        ]
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "on_unsubscribe": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "on_reply": {
                                                                            "type": "boolean",
                                                                            "description": "Leave the journey when the contact replies to any of its emails (auto-replies ignored)."
                                                                        },
                                                                        "segments_entered": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "type": "string"
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "stream": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "marketing",
                                                                        "transactional"
                                                                    ]
                                                                },
                                                                "cooldown_hours": {
                                                                    "type": "integer",
                                                                    "nullable": true
                                                                }
                                                            }
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true,
                                                            "description": "The editable draft: {nodes[{id,type,config}], edges[{from,to,branch?}]}. Publishing snapshots it into a version."
                                                        },
                                                        "validation": {
                                                            "type": "object",
                                                            "properties": {
                                                                "ok": {
                                                                    "type": "boolean"
                                                                },
                                                                "errors": {
                                                                    "type": "object",
                                                                    "additionalProperties": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "description": "Problems keyed by node id (nodes.<id>.<field>) or graph/settings."
                                                                }
                                                            }
                                                        },
                                                        "live_version": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "number": {
                                                                    "type": "integer"
                                                                },
                                                                "published_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                }
                                                            }
                                                        },
                                                        "paused_by": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "user",
                                                                "breaker"
                                                            ]
                                                        },
                                                        "counts": {
                                                            "type": "object",
                                                            "properties": {
                                                                "in_flight": {
                                                                    "type": "integer",
                                                                    "description": "Runs that have not finished."
                                                                },
                                                                "completed": {
                                                                    "type": "integer"
                                                                },
                                                                "exited": {
                                                                    "type": "integer"
                                                                },
                                                                "failed": {
                                                                    "type": "integer"
                                                                },
                                                                "emails_sent": {
                                                                    "type": "integer",
                                                                    "description": "Emails this automation has actually sent, across every version. Only counted on the list; 0 elsewhere."
                                                                }
                                                            }
                                                        },
                                                        "published_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "paused_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "archived_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "variant": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "description": "The ID of the winning version. Every contact gets it from now on."
                                    }
                                },
                                "required": [
                                    "variant"
                                ]
                            },
                            "example": {
                                "variant": "variant"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/automations/{automation}/stats": {
            "get": {
                "operationId": "getAutomationsAutomationStats",
                "summary": "Stats a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "automation_id": {
                                                            "type": "string"
                                                        },
                                                        "version_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Counters belong to the live version."
                                                        },
                                                        "in_flight_total": {
                                                            "type": "integer"
                                                        },
                                                        "nodes": {
                                                            "type": "object",
                                                            "description": "Keyed by node id.",
                                                            "additionalProperties": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "entered": {
                                                                        "type": "integer"
                                                                    },
                                                                    "completed": {
                                                                        "type": "integer"
                                                                    },
                                                                    "skipped": {
                                                                        "type": "integer"
                                                                    },
                                                                    "converted": {
                                                                        "type": "integer"
                                                                    },
                                                                    "in_flight": {
                                                                        "type": "integer",
                                                                        "description": "Runs currently at this node."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/automations/{automation}/dry-run": {
            "post": {
                "operationId": "postAutomationsAutomationDryRun",
                "summary": "Preview an automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "trigger": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true
                                                        },
                                                        "matching_today": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Contacts who match the trigger today. Null when the trigger has no audience to count (an event nobody has sent yet)."
                                                        },
                                                        "unsubscribed": {
                                                            "type": "integer",
                                                            "nullable": true
                                                        },
                                                        "not_mailable": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Unsubscribed, bounced, complained or unconfirmed."
                                                        },
                                                        "would_be_capped": {
                                                            "type": "integer"
                                                        },
                                                        "samples": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "contact": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "email": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            }
                                                                        }
                                                                    },
                                                                    "timeline": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "node_id": {
                                                                                    "type": "string"
                                                                                },
                                                                                "type": {
                                                                                    "type": "string"
                                                                                },
                                                                                "summary": {
                                                                                    "type": "string"
                                                                                },
                                                                                "branch": {
                                                                                    "type": "string",
                                                                                    "nullable": true
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "sandbox_messages": {
                                                            "type": "array",
                                                            "description": "Present only when the request asked for `deliver_to_sandbox`: one entry per email a sample contact reached, in walk order.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "contact": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "id": {
                                                                                "type": "string"
                                                                            },
                                                                            "email": {
                                                                                "type": "string"
                                                                            },
                                                                            "name": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            }
                                                                        }
                                                                    },
                                                                    "node_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "sandbox_message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Open it with GET /sandbox/messages/{id}. Null when this email could not be built; see `error`."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Walks the current draft for up to three real contacts with the checks made for real and the waits skipped, and \u2014 where the start can be counted in advance \u2014 how many people would enter today. Sends nothing and writes nothing.\n\nPass `deliver_to_sandbox: true` to also put each email those contacts would receive into your **Sandbox**, built exactly as a real run builds it, so you can open the actual message. Nothing is delivered, no run is recorded and no credits are used; `sandbox_messages` in the response lists what landed. Refused with `422` when the Sandbox is not available.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "deliver_to_sandbox": {
                                        "type": "boolean",
                                        "default": false,
                                        "description": "Also submit the sample contacts' emails to your Sandbox."
                                    }
                                }
                            },
                            "example": {
                                "deliver_to_sandbox": true
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/contact-events": {
            "post": {
                "operationId": "postContactEvents",
                "summary": "Record contact events",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "contact_events:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "202": {
                        "description": "Accepted. Read `rejected` \u2014 a 202 does not mean every event was recorded.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "accepted": {
                                                            "type": "integer",
                                                            "description": "Events recorded."
                                                        },
                                                        "duplicates": {
                                                            "type": "integer",
                                                            "description": "Events already recorded under the same unique_id; nothing happened twice."
                                                        },
                                                        "rejected": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "index": {
                                                                        "type": "integer",
                                                                        "description": "Position in the events array you sent."
                                                                    },
                                                                    "reason": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Tells Mailyte that something happened to a person in your own system \u2014 a checkout started,\nan order completed, an application submitted. Automations that start on that event, wait\nfor it or leave on it react within seconds. Read\n[Sending contact events](/developer/guides/sending-contact-events) before you integrate.\n\nSend up to **500 events** in `events`, or post a single event's fields at the top level.\nEach event is checked on its own: a bad one is listed in `rejected` with its position and\nthe reason, and the others are recorded. The request fails as a whole only when its shape\nis wrong \u2014 no events, more than 500, an item that is not an object \u2014 or the key lacks\n`contact_events:write`.\n\nFour things to know before you send the first one:\n\n1. **An event is not consent.** An `email` we have never seen creates a contact with the\n   status `unconfirmed`. It can enter automations, but no automated email reaches it until\n   the contact is subscribed. Record consent through the contacts endpoints, not here.\n2. **Send `unique_id`.** Repeating an event with the same `unique_id` is counted under\n   `duplicates` and changes nothing, which is what makes a retry safe. Without one, a\n   key is derived from the event's name, person, time and properties \u2014 which only\n   catches an exact repeat.\n3. **Old events never start anything.** An event whose `occurred_at` is more than 7 days\n   before we receive it is stored as historical and never starts, moves or ends a journey.\n   Events are kept for 90 days from `occurred_at`, so anything older is removed overnight.\n4. **The limit is 600 requests a minute** per organization, across all its keys. Batch\n   rather than sending one request per event.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "events"
                                ],
                                "properties": {
                                    "events": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 500,
                                        "description": "The events to record. To send one event you may instead put its fields at the top level of the body.",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "event"
                                            ],
                                            "properties": {
                                                "event": {
                                                    "type": "string",
                                                    "pattern": "^[a-z][a-z0-9_]{0,63}$",
                                                    "description": "What happened, in lowercase snake_case starting with a letter, up to 64 characters: `checkout_started`, `order_completed`. This is the name the automation builder offers.",
                                                    "x-example": "opened"
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "format": "email",
                                                    "description": "Who it happened to. Matched case-insensitively; an address we have not seen creates an `unconfirmed` contact. Send this or `contact_id`."
                                                },
                                                "contact_id": {
                                                    "type": "string",
                                                    "description": "The contact's Mailyte id, instead of `email`. Wins when both are sent. Must belong to your organization.",
                                                    "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "maxLength": 255,
                                                    "description": "The person's name. Used only when this event creates the contact; never changes an existing one.",
                                                    "x-example": "Spring newsletter"
                                                },
                                                "occurred_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "description": "When it happened, ISO 8601 with an offset. Defaults to now. At most five minutes in the future. More than 7 days in the past makes it historical: stored, and never starts or moves a journey."
                                                },
                                                "unique_id": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "description": "Your own id for this occurrence \u2014 an order number, a checkout id. Unique per organization: a repeat is reported as a duplicate and ignored."
                                                },
                                                "properties": {
                                                    "type": "object",
                                                    "additionalProperties": true,
                                                    "description": "Anything about it, up to 16 KB as JSON. Available to the journey as `{{ event.<key> }}` in emails and to its checks, e.g. `event.total`."
                                                }
                                            }
                                        }
                                    }
                                }
                            },
                            "example": {
                                "events": [
                                    {
                                        "event": "checkout_started",
                                        "email": "ada@example.com",
                                        "occurred_at": "2026-09-23T10:04:11+01:00",
                                        "unique_id": "checkout-81234",
                                        "properties": {
                                            "cart_value": 45000,
                                            "currency": "NGN",
                                            "items": 3
                                        }
                                    },
                                    {
                                        "event": "order_completed",
                                        "email": "tunde@example.com",
                                        "unique_id": "order-50917",
                                        "properties": {
                                            "total": 12500,
                                            "category": "consumable"
                                        }
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/contact-events/names": {
            "get": {
                "operationId": "getContactEventsNames",
                "summary": "List event names",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "days",
                        "in": "query",
                        "required": false,
                        "description": "How far back to look, 1 to 365. Default 90, which is also how long events are kept.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "name": {
                                                                "type": "string",
                                                                "description": "The event name, e.g. order_completed, or a built-in one like email.clicked."
                                                            },
                                                            "built_in": {
                                                                "type": "boolean",
                                                                "description": "Raised by Mailyte itself rather than sent by your systems; always available."
                                                            },
                                                            "count": {
                                                                "type": "integer",
                                                                "description": "How many have been received, over the window asked for. 0 for a built-in name nobody has triggered yet."
                                                            },
                                                            "last_seen_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "The event names an automation can use: Mailyte's own (`built_in`, always listed), then every\nname your systems have sent in the window, most recently seen first, up to 100. This is\nwhat the automation builder's event list is made from, so a name appears there as soon as\nthe first event carrying it is received \u2014 historical ones included."
            }
        },
        "/api/v1/automations/assistant/propose": {
            "post": {
                "operationId": "postAutomationsAssistantPropose",
                "summary": "Propose (automation)",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "summary": {
                                                            "type": "string",
                                                            "description": "What the proposed journey does, in a sentence or two."
                                                        },
                                                        "graph": {
                                                            "type": "object",
                                                            "description": "The proposed journey, shaped exactly like a recipe: apply it with PUT /automations/{automation}. Not saved.",
                                                            "properties": {
                                                                "nodes": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "additionalProperties": true
                                                                    }
                                                                },
                                                                "edges": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "additionalProperties": true
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "unresolved": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "Ids of steps left for the caller to finish, such as a sender or list Maya could not choose."
                                                        },
                                                        "repairs": {
                                                            "type": "integer",
                                                            "description": "How many times the proposal was corrected before it passed validation."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "intent": {
                                        "type": "string",
                                        "minLength": 3,
                                        "maxLength": 2000,
                                        "description": "What the automation should do, in your own words, like \"welcome new sign-ups with three emails over a week\".",
                                        "x-example": "Welcome new sign-ups with three emails over a week"
                                    },
                                    "automation_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "Optional. The automation being edited, so the suggestion builds on it."
                                    },
                                    "graph": {
                                        "nullable": true,
                                        "type": "object",
                                        "properties": {
                                            "nodes": {
                                                "nullable": true,
                                                "type": "array",
                                                "description": "The steps, each `{\"id\", \"type\", \"config\"}`. `GET /automations/node-types` lists the types and what goes in `config`."
                                            },
                                            "edges": {
                                                "nullable": true,
                                                "type": "array",
                                                "description": "How the steps connect, each `{\"from\", \"to\"}` with step IDs, plus `\"branch\"` after a step that splits."
                                            }
                                        },
                                        "additionalProperties": true,
                                        "description": "Optional. The steps as they stand, as `{\"nodes\": [...], \"edges\": [...]}`, to build on."
                                    },
                                    "history": {
                                        "nullable": true,
                                        "type": "array",
                                        "maxItems": 10,
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "role": {
                                                    "type": "string",
                                                    "enum": [
                                                        "you",
                                                        "maya"
                                                    ],
                                                    "description": "`you` for your messages, `maya` for the assistant's."
                                                },
                                                "content": {
                                                    "type": "string",
                                                    "maxLength": 2000,
                                                    "description": "What was said.",
                                                    "x-example": {
                                                        "headline": "Our October update"
                                                    }
                                                }
                                            }
                                        },
                                        "description": "Optional. The conversation so far, so a follow-up builds on it."
                                    }
                                },
                                "required": [
                                    "intent"
                                ]
                            },
                            "example": {
                                "intent": "Welcome new sign-ups with three emails over a week"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/automations/{automation}/assistant/email/{node}": {
            "post": {
                "operationId": "postAutomationsAutomationAssistantEmailNode",
                "summary": "Create a automation",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "node",
                        "in": "path",
                        "required": true,
                        "description": "The node identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "subject": {
                                                            "type": "string"
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "description": "The email body. A marketing step always carries an unsubscribe link."
                                                        },
                                                        "note": {
                                                            "type": "string",
                                                            "description": "Anything Maya wants the author to check before using it."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "graph": {
                                        "type": "object",
                                        "properties": {
                                            "nodes": {
                                                "type": "array",
                                                "description": "The steps, each `{\"id\", \"type\", \"config\"}`. `GET /automations/node-types` lists the types and what goes in `config`."
                                            }
                                        },
                                        "required": [
                                            "nodes"
                                        ],
                                        "additionalProperties": true,
                                        "description": "The automation's steps as they stand, as `{\"nodes\": [...], \"edges\": [...]}`."
                                    },
                                    "instruction": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 2000,
                                        "description": "Optional. What to change about this email, in your own words.",
                                        "x-example": "Make it shorter and friendlier"
                                    }
                                },
                                "required": [
                                    "graph"
                                ]
                            },
                            "example": {
                                "graph": {
                                    "nodes": [
                                        "node"
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/automations/{automation}/runs/{run}/assistant/explain": {
            "post": {
                "operationId": "postAutomationsAutomationRunsRunAssistantExplain",
                "summary": "Explain (automation)",
                "tags": [
                    "Automations"
                ],
                "x-required-scope": "automations:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "automation",
                        "in": "path",
                        "required": true,
                        "description": "The automation identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "run",
                        "in": "path",
                        "required": true,
                        "description": "The run identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "answer": {
                                                            "type": "string",
                                                            "description": "What happened on this run, in plain words."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "question": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Optional. What you want to know about this run, in your own words."
                                    }
                                }
                            },
                            "example": {
                                "question": "question"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/sandbox/usage": {
            "get": {
                "operationId": "getSandboxUsage",
                "summary": "Get sandbox usage",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "inboxes": {
                                                            "type": "integer",
                                                            "description": "Inboxes the organization has now."
                                                        },
                                                        "inbox_limit": {
                                                            "type": "integer"
                                                        },
                                                        "month": {
                                                            "type": "string",
                                                            "description": "The calendar month counted, `YYYY-MM` (UTC)."
                                                        },
                                                        "month_accepted": {
                                                            "type": "integer",
                                                            "description": "Messages accepted this month, across every inbox."
                                                        },
                                                        "monthly_limit": {
                                                            "type": "integer",
                                                            "description": "Past it, new messages are refused until the month turns."
                                                        },
                                                        "max_message_bytes": {
                                                            "type": "integer"
                                                        },
                                                        "max_messages": {
                                                            "type": "integer",
                                                            "description": "The most any one inbox keeps."
                                                        },
                                                        "retention_days": {
                                                            "type": "integer",
                                                            "description": "The longest any message is kept."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Where your organization stands against the sandbox limits: inboxes used, messages accepted this month, and the per-inbox and per-message limits. The sandbox is free on every plan and never uses sending credits."
            }
        },
        "/api/v1/sandbox/inboxes": {
            "get": {
                "operationId": "getSandboxInboxes",
                "summary": "List sandbox inboxes",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "items": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "ULID, issued by the mail server (uppercase)."
                                                                    },
                                                                    "organization_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "Your label, e.g. \"Staging\" or \"CI\"."
                                                                    },
                                                                    "username": {
                                                                        "type": "string",
                                                                        "description": "The SMTP username for this inbox (`sbx_\u2026`). Authenticate with it on `smtp_host`."
                                                                    },
                                                                    "smtp_host": {
                                                                        "type": "string",
                                                                        "description": "The sandbox SMTP host, `sandbox.smtp.mailyte.com`."
                                                                    },
                                                                    "smtp_ports": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "integer"
                                                                        },
                                                                        "description": "2525 (STARTTLS) and 2465 (implicit TLS). The production ports 587/465 do not accept sandbox credentials."
                                                                    },
                                                                    "max_messages": {
                                                                        "type": "integer",
                                                                        "description": "How many messages the inbox keeps. The oldest is deleted when a new one would exceed it."
                                                                    },
                                                                    "retention_days": {
                                                                        "type": "integer",
                                                                        "description": "Messages older than this are deleted."
                                                                    },
                                                                    "inbound_address": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "An address anyone can send to from anywhere, with no SMTP login, that lands in this inbox. Use it as a third-party service's notification address."
                                                                    },
                                                                    "is_default": {
                                                                        "type": "boolean",
                                                                        "description": "Test-mode API sends land in the default inbox. The first inbox you create is the default."
                                                                    },
                                                                    "share_enabled": {
                                                                        "type": "boolean",
                                                                        "description": "The inbox's public link is on. Read the link and access code with `GET /sandbox/inboxes/{id}/share`."
                                                                    },
                                                                    "message_count": {
                                                                        "type": "integer"
                                                                    },
                                                                    "unread_count": {
                                                                        "type": "integer"
                                                                    },
                                                                    "last_message_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the newest message arrived. Null when the inbox has never had one."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "description": "When the inbox was created."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Matching rows in all, not just this page."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "A sandbox inbox catches mail and never delivers it. Point any SMTP client at `sandbox.smtp.mailyte.com` (port 2525 with STARTTLS, or 2465 with TLS) using an inbox's `username` and secret, or send through `POST /messages` with a **test-mode API key**, and the message lands here instead of anyone's mailbox. Nothing the sandbox does reaches your live event log, live webhooks, suppression list or sending credits."
            },
            "post": {
                "operationId": "postSandboxInboxes",
                "summary": "Create a sandbox inbox",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "ULID, issued by the mail server (uppercase)."
                                                        },
                                                        "organization_id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your label, e.g. \"Staging\" or \"CI\"."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username for this inbox (`sbx_\u2026`). Authenticate with it on `smtp_host`."
                                                        },
                                                        "smtp_host": {
                                                            "type": "string",
                                                            "description": "The sandbox SMTP host, `sandbox.smtp.mailyte.com`."
                                                        },
                                                        "smtp_ports": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "integer"
                                                            },
                                                            "description": "2525 (STARTTLS) and 2465 (implicit TLS). The production ports 587/465 do not accept sandbox credentials."
                                                        },
                                                        "max_messages": {
                                                            "type": "integer",
                                                            "description": "How many messages the inbox keeps. The oldest is deleted when a new one would exceed it."
                                                        },
                                                        "retention_days": {
                                                            "type": "integer",
                                                            "description": "Messages older than this are deleted."
                                                        },
                                                        "inbound_address": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "An address anyone can send to from anywhere, with no SMTP login, that lands in this inbox. Use it as a third-party service's notification address."
                                                        },
                                                        "is_default": {
                                                            "type": "boolean",
                                                            "description": "Test-mode API sends land in the default inbox. The first inbox you create is the default."
                                                        },
                                                        "share_enabled": {
                                                            "type": "boolean",
                                                            "description": "The inbox's public link is on. Read the link and access code with `GET /sandbox/inboxes/{id}/share`."
                                                        },
                                                        "message_count": {
                                                            "type": "integer"
                                                        },
                                                        "unread_count": {
                                                            "type": "integer"
                                                        },
                                                        "last_message_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the newest message arrived. Null when the inbox has never had one."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the inbox was created."
                                                        },
                                                        "secret": {
                                                            "type": "string",
                                                            "description": "The SMTP password (`mlt_sbx_\u2026`), on the call that creates the inbox only. Read it again any time with `GET /sandbox/inboxes/{id}/credentials`."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "name": "Staging"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Returns the inbox with its SMTP `secret`. Sandbox credentials stay viewable: read them again any time with `GET /sandbox/inboxes/{id}/credentials`. Your first inbox becomes the default, which is where test-mode API sends land. An organization may have 3 inboxes. Owners and admins only.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "Its name, shown in the dashboard.",
                                        "x-example": "Spring newsletter"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Spring newsletter"
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/sandbox/inboxes/{id}": {
            "get": {
                "operationId": "getSandboxInboxesId",
                "summary": "Get a sandbox inbox",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "ULID, issued by the mail server (uppercase)."
                                                        },
                                                        "organization_id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your label, e.g. \"Staging\" or \"CI\"."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username for this inbox (`sbx_\u2026`). Authenticate with it on `smtp_host`."
                                                        },
                                                        "smtp_host": {
                                                            "type": "string",
                                                            "description": "The sandbox SMTP host, `sandbox.smtp.mailyte.com`."
                                                        },
                                                        "smtp_ports": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "integer"
                                                            },
                                                            "description": "2525 (STARTTLS) and 2465 (implicit TLS). The production ports 587/465 do not accept sandbox credentials."
                                                        },
                                                        "max_messages": {
                                                            "type": "integer",
                                                            "description": "How many messages the inbox keeps. The oldest is deleted when a new one would exceed it."
                                                        },
                                                        "retention_days": {
                                                            "type": "integer",
                                                            "description": "Messages older than this are deleted."
                                                        },
                                                        "inbound_address": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "An address anyone can send to from anywhere, with no SMTP login, that lands in this inbox. Use it as a third-party service's notification address."
                                                        },
                                                        "is_default": {
                                                            "type": "boolean",
                                                            "description": "Test-mode API sends land in the default inbox. The first inbox you create is the default."
                                                        },
                                                        "share_enabled": {
                                                            "type": "boolean",
                                                            "description": "The inbox's public link is on. Read the link and access code with `GET /sandbox/inboxes/{id}/share`."
                                                        },
                                                        "message_count": {
                                                            "type": "integer"
                                                        },
                                                        "unread_count": {
                                                            "type": "integer"
                                                        },
                                                        "last_message_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the newest message arrived. Null when the inbox has never had one."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the inbox was created."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "patch": {
                "operationId": "patchSandboxInboxesId",
                "summary": "Update a sandbox inbox",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "ULID, issued by the mail server (uppercase)."
                                                        },
                                                        "organization_id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "description": "Your label, e.g. \"Staging\" or \"CI\"."
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username for this inbox (`sbx_\u2026`). Authenticate with it on `smtp_host`."
                                                        },
                                                        "smtp_host": {
                                                            "type": "string",
                                                            "description": "The sandbox SMTP host, `sandbox.smtp.mailyte.com`."
                                                        },
                                                        "smtp_ports": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "integer"
                                                            },
                                                            "description": "2525 (STARTTLS) and 2465 (implicit TLS). The production ports 587/465 do not accept sandbox credentials."
                                                        },
                                                        "max_messages": {
                                                            "type": "integer",
                                                            "description": "How many messages the inbox keeps. The oldest is deleted when a new one would exceed it."
                                                        },
                                                        "retention_days": {
                                                            "type": "integer",
                                                            "description": "Messages older than this are deleted."
                                                        },
                                                        "inbound_address": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "An address anyone can send to from anywhere, with no SMTP login, that lands in this inbox. Use it as a third-party service's notification address."
                                                        },
                                                        "is_default": {
                                                            "type": "boolean",
                                                            "description": "Test-mode API sends land in the default inbox. The first inbox you create is the default."
                                                        },
                                                        "share_enabled": {
                                                            "type": "boolean",
                                                            "description": "The inbox's public link is on. Read the link and access code with `GET /sandbox/inboxes/{id}/share`."
                                                        },
                                                        "message_count": {
                                                            "type": "integer"
                                                        },
                                                        "unread_count": {
                                                            "type": "integer"
                                                        },
                                                        "last_message_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the newest message arrived. Null when the inbox has never had one."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the inbox was created."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Rename it, change how many messages it keeps (at most 50) or for how long (at most 30 days), or make it the default. Setting `is_default` clears it on your other inboxes. Owners and admins only.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "Its name, shown in the dashboard.",
                                        "x-example": "Spring newsletter"
                                    },
                                    "max_messages": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "How many messages the inbox keeps. Past this, the oldest are deleted.",
                                        "x-example": 500
                                    },
                                    "retention_days": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "How many days messages are kept.",
                                        "x-example": 7
                                    },
                                    "is_default": {
                                        "type": "boolean",
                                        "description": "Make this your default Sandbox inbox.",
                                        "x-example": true
                                    }
                                }
                            },
                            "example": {
                                "name": "Spring newsletter",
                                "max_messages": 500
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteSandboxInboxesId",
                "summary": "Delete a sandbox inbox",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The inbox is deleted with every message in it; its SMTP credential stops working at once."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Deletes the inbox and every message in it. Its SMTP credential stops working at once. Owners and admins only."
            }
        },
        "/api/v1/sandbox/inboxes/{id}/credentials": {
            "get": {
                "operationId": "getSandboxInboxesIdCredentials",
                "summary": "Get a sandbox inbox's SMTP credentials",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "username": {
                                                            "type": "string",
                                                            "description": "The SMTP username (`sbx_\u2026`)."
                                                        },
                                                        "secret": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The SMTP password (`mlt_sbx_\u2026`). Null for an inbox created before sandbox credentials became viewable: reset its credentials to get one you can see."
                                                        },
                                                        "smtp_host": {
                                                            "type": "string",
                                                            "description": "The sandbox SMTP host, `sandbox.smtp.mailyte.com`."
                                                        },
                                                        "smtp_ports": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "integer"
                                                            },
                                                            "description": "2525 (STARTTLS) and 2465 (implicit TLS)."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "The inbox's SMTP username and secret, with the host and ports to use them on. Unlike live SMTP credentials and API keys, sandbox credentials are always viewable: they can only drop mail into your own sandbox, never deliver it. `secret` is null for an inbox created before this was possible; reset its credentials to get one. Needs a key with `sandbox:write`, because it reveals a secret."
            }
        },
        "/api/v1/sandbox/inboxes/{id}/reset-credentials": {
            "post": {
                "operationId": "postSandboxInboxesIdResetCredentials",
                "summary": "Reset a sandbox inbox's SMTP credentials",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "username": {
                                                            "type": "string"
                                                        },
                                                        "secret": {
                                                            "type": "string",
                                                            "description": "The new SMTP password. The old one no longer works."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Issues a new username and secret. The old ones stop working immediately, so update anything configured with them. Owners and admins only.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/sandbox/inboxes/{id}/empty": {
            "post": {
                "operationId": "postSandboxInboxesIdEmpty",
                "summary": "Empty a sandbox inbox",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "deleted": {
                                                            "type": "integer",
                                                            "description": "How many messages were deleted."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Deletes every message in the inbox and keeps the inbox and its credentials.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/sandbox/inboxes/{id}/share": {
            "get": {
                "operationId": "getSandboxInboxesIdShare",
                "summary": "Get a sandbox inbox's public link and access code",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "The public link opens the inbox. When false the link answers \"not available\"."
                                                        },
                                                        "code_required": {
                                                            "type": "boolean",
                                                            "description": "Visitors must enter `code` before they see anything."
                                                        },
                                                        "code": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The 6-digit access code."
                                                        },
                                                        "token": {
                                                            "type": "string",
                                                            "description": "The secret part of the link (24 characters)."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The public link to share, e.g. `https://mailyte.com/sandbox/<token>`."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the link or code last changed. Every change signs all visitors out."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Every sandbox inbox has a public link that opens a read-only view of it, with no Mailyte account needed, so a teammate, a tester or a client can see what your app sent. By default the link asks for a 6-digit access code first. Visitors see the messages (HTML, text, headers, attachments, spam and client checks); they never see the SMTP credentials, webhooks, or anything they could change. The link and code are always viewable here. Needs `sandbox:write`, because the code opens the inbox to whoever you give it to."
            },
            "patch": {
                "operationId": "patchSandboxInboxesIdShare",
                "summary": "Turn a sandbox inbox's public link or access code on or off",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "The public link opens the inbox. When false the link answers \"not available\"."
                                                        },
                                                        "code_required": {
                                                            "type": "boolean",
                                                            "description": "Visitors must enter `code` before they see anything."
                                                        },
                                                        "code": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The 6-digit access code."
                                                        },
                                                        "token": {
                                                            "type": "string",
                                                            "description": "The secret part of the link (24 characters)."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The public link to share, e.g. `https://mailyte.com/sandbox/<token>`."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the link or code last changed. Every change signs all visitors out."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "code_required": false
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Send `enabled` to turn the link on or off (off: the link says \"not available\"), and `code_required` to ask for the code or open the link directly. Every change signs out everyone who was viewing. Owners and admins only.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "enabled": {
                                        "type": "boolean",
                                        "description": "Whether it is switched on.",
                                        "x-example": true
                                    },
                                    "code_required": {
                                        "type": "boolean",
                                        "description": "Whether people opening the share link must also type the access code.",
                                        "x-example": true
                                    }
                                }
                            },
                            "example": {
                                "enabled": true,
                                "code_required": true
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/sandbox/inboxes/{id}/share/reset-link": {
            "post": {
                "operationId": "postSandboxInboxesIdShareResetLink",
                "summary": "Give a sandbox inbox a new public link",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "The public link opens the inbox. When false the link answers \"not available\"."
                                                        },
                                                        "code_required": {
                                                            "type": "boolean",
                                                            "description": "Visitors must enter `code` before they see anything."
                                                        },
                                                        "code": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The 6-digit access code."
                                                        },
                                                        "token": {
                                                            "type": "string",
                                                            "description": "The secret part of the link (24 characters)."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The public link to share, e.g. `https://mailyte.com/sandbox/<token>`."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the link or code last changed. Every change signs all visitors out."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Issues a new link; the old one stops working at once and everyone viewing is signed out. The access code stays the same. Owners and admins only.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/sandbox/inboxes/{id}/share/new-code": {
            "post": {
                "operationId": "postSandboxInboxesIdShareNewCode",
                "summary": "Give a sandbox inbox a new access code",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "The public link opens the inbox. When false the link answers \"not available\"."
                                                        },
                                                        "code_required": {
                                                            "type": "boolean",
                                                            "description": "Visitors must enter `code` before they see anything."
                                                        },
                                                        "code": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The 6-digit access code."
                                                        },
                                                        "token": {
                                                            "type": "string",
                                                            "description": "The secret part of the link (24 characters)."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The public link to share, e.g. `https://mailyte.com/sandbox/<token>`."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the link or code last changed. Every change signs all visitors out."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Issues a new 6-digit code; the old one stops working and everyone who unlocked with it is signed out. The link stays the same. Owners and admins only.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/sandbox/inboxes/{id}/messages": {
            "get": {
                "operationId": "getSandboxInboxesIdMessages",
                "summary": "List messages in a sandbox inbox",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Matches subject, From or To (contains).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Page size, at most 100.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "description": "Rows to skip.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "items": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "ULID of the stored message."
                                                                    },
                                                                    "inbox_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "subject": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "header_from": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The From header, as written."
                                                                    },
                                                                    "header_to": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "The To header addresses."
                                                                    },
                                                                    "envelope_rcpts": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "Every address the message was sent to, INCLUDING Bcc: blind recipients are in the envelope, never in the headers, so this is the only place they show."
                                                                    },
                                                                    "size_bytes": {
                                                                        "type": "integer"
                                                                    },
                                                                    "attachment_count": {
                                                                        "type": "integer"
                                                                    },
                                                                    "source": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "smtp",
                                                                            "api",
                                                                            "inbound"
                                                                        ],
                                                                        "description": "`api` for a test-mode API key send; `inbound` for mail sent to the inbox's `inbound_address`."
                                                                    },
                                                                    "simulated_outcome": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "delivered",
                                                                            "bounce",
                                                                            "softbounce",
                                                                            "complaint",
                                                                            "suppressed"
                                                                        ],
                                                                        "description": "The outcome simulated for this message, set by a `@sim.mailyte.com` address or an `X-Mailyte-Simulate` header. Null means the default: accepted, then delivered."
                                                                    },
                                                                    "spam_score": {
                                                                        "type": "number",
                                                                        "nullable": true,
                                                                        "description": "Null until the message has been scored; scoring runs after it arrives."
                                                                    },
                                                                    "read_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When it was marked read. Null means unread."
                                                                    },
                                                                    "received_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "description": "When the sandbox accepted it."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Matching rows in all, not just this page."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Newest first. An inbox keeps its newest 50 messages for 30 days; older ones are deleted automatically."
            }
        },
        "/api/v1/sandbox/inboxes/{id}/messages/await": {
            "get": {
                "operationId": "getSandboxInboxesIdMessagesAwait",
                "summary": "Wait for a sandbox message",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "description": "A recipient address (envelope or To header).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "subject",
                        "in": "query",
                        "required": false,
                        "description": "Text the subject contains.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "ISO 8601. Only messages received after this count.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "timeout",
                        "in": "query",
                        "required": false,
                        "description": "Seconds to wait, 1\u201330. Default 30.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "ULID of the stored message."
                                                        },
                                                        "inbox_id": {
                                                            "type": "string"
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "header_from": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The From header, as written."
                                                        },
                                                        "header_to": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The To header addresses."
                                                        },
                                                        "envelope_rcpts": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "Every address the message was sent to, INCLUDING Bcc: blind recipients are in the envelope, never in the headers, so this is the only place they show."
                                                        },
                                                        "size_bytes": {
                                                            "type": "integer"
                                                        },
                                                        "attachment_count": {
                                                            "type": "integer"
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp",
                                                                "api",
                                                                "inbound"
                                                            ],
                                                            "description": "`api` for a test-mode API key send; `inbound` for mail sent to the inbox's `inbound_address`."
                                                        },
                                                        "simulated_outcome": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "delivered",
                                                                "bounce",
                                                                "softbounce",
                                                                "complaint",
                                                                "suppressed"
                                                            ],
                                                            "description": "The outcome simulated for this message, set by a `@sim.mailyte.com` address or an `X-Mailyte-Simulate` header. Null means the default: accepted, then delivered."
                                                        },
                                                        "spam_score": {
                                                            "type": "number",
                                                            "nullable": true,
                                                            "description": "Null until the message has been scored; scoring runs after it arrives."
                                                        },
                                                        "read_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was marked read. Null means unread."
                                                        },
                                                        "received_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the sandbox accepted it."
                                                        },
                                                        "headers": {
                                                            "type": "array",
                                                            "description": "Every header in order, repeated names included.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "value": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The text/plain part, decoded. Null when there is none."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The text/html part, decoded and NOT sanitised: it is exactly what your code sent. Render it only in a sandboxed frame with scripts disabled."
                                                        },
                                                        "attachments": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "index": {
                                                                        "type": "integer",
                                                                        "description": "Pass to GET /sandbox/messages/{id}/attachments/{index}."
                                                                    },
                                                                    "filename": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "content_type": {
                                                                        "type": "string"
                                                                    },
                                                                    "size": {
                                                                        "type": "integer"
                                                                    },
                                                                    "content_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Set for an inline (cid:) part."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "events": {
                                                            "type": "array",
                                                            "description": "The simulated delivery timeline. These exist only in the sandbox: they never reach your suppression list, your live event log or your live webhooks.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "event_type": {
                                                                        "type": "string",
                                                                        "description": "e.g. `email.accepted`, `email.delivered`, `email.bounced`."
                                                                    },
                                                                    "recipient": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "detail": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "additionalProperties": true
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "webhook_deliveries": {
                                                            "type": "array",
                                                            "description": "Every sandbox webhook attempt this message caused, with your endpoint's response.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "integer"
                                                                    },
                                                                    "webhook_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The sandbox message that caused it. Null for a `sandbox.test` event."
                                                                    },
                                                                    "event_type": {
                                                                        "type": "string"
                                                                    },
                                                                    "attempt": {
                                                                        "type": "integer",
                                                                        "description": "1 to 5. Retries back off 30 s, 2 min, 5 min, 15 min, 30 min."
                                                                    },
                                                                    "status_code": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Null when no response arrived; see `error`."
                                                                    },
                                                                    "duration_ms": {
                                                                        "type": "integer",
                                                                        "nullable": true
                                                                    },
                                                                    "response_excerpt": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The first 1 KB of your response body."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why no response arrived (timeout, refused, blocked address)."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "description": "When the attempt was made."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "spam": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The spam filter's verdict, as a receiving server would score it. Null until `analysed_at` is set; null after that means scoring was unavailable.",
                                                            "properties": {
                                                                "score": {
                                                                    "type": "number"
                                                                },
                                                                "required_score": {
                                                                    "type": "number",
                                                                    "description": "The score at which mail is treated as spam."
                                                                },
                                                                "action": {
                                                                    "type": "string",
                                                                    "description": "e.g. `no action`, `add header`, `reject`."
                                                                },
                                                                "symbols": {
                                                                    "type": "array",
                                                                    "description": "The rules that fired, largest effect first.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "score": {
                                                                                "type": "number"
                                                                            },
                                                                            "description": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            },
                                                                            "options": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "checks": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "description": "Problems found in the message, such as a missing text part, images without alt text, insecure links, or no List-Unsubscribe on bulk mail. `[]` means none. Null means it has not been checked yet (see `analysed_at`).",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "severity": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "error",
                                                                            "warning",
                                                                            "info"
                                                                        ]
                                                                    },
                                                                    "title": {
                                                                        "type": "string"
                                                                    },
                                                                    "detail": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "html_support": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "How well the HTML is supported across email clients. Null for a message with no HTML part, before `analysed_at` is set, or if the step failed.",
                                                            "properties": {
                                                                "score_pct": {
                                                                    "type": "integer",
                                                                    "description": "Market-share-weighted share of clients that fully support every feature used."
                                                                },
                                                                "detected_count": {
                                                                    "type": "integer"
                                                                },
                                                                "clients": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "family": {
                                                                                "type": "string"
                                                                            },
                                                                            "support": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "full",
                                                                                    "partial",
                                                                                    "none"
                                                                                ]
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "features": {
                                                                    "type": "array",
                                                                    "description": "Features the message uses that fail or are partial somewhere.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "slug": {
                                                                                "type": "string"
                                                                            },
                                                                            "title": {
                                                                                "type": "string"
                                                                            },
                                                                            "unsupported_in": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                }
                                                                            },
                                                                            "partial_in": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "analysed_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When analysis finished. It runs a few seconds after the message arrives; until then `spam`, `checks` and `html_support` are null."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "204": {
                        "description": "The wait ran out with no matching message. Call again to keep waiting."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Holds the request open until a message matching your filters arrives in the inbox, then\nreturns it in full (the same object as `GET /sandbox/messages/{id}`). If nothing matches\nwithin `timeout` seconds the answer is **`204 No Content`** \u2014 \"not yet\", not an error \u2014\nso a test can simply call again.\n\nThis is the call for end-to-end tests: trigger the action in your app, then wait for the\nemail it should have sent and assert on its subject, HTML or links.\n\n- Pass `since` (the time your test started) so a message from an earlier run never\n  satisfies this one. Only messages received **after** it are considered.\n- `to` matches any recipient, including Bcc. `subject` matches if it is contained in the\n  subject.\n- At most five waits can be open at once per organization; the sixth gets `429`.\n\nA CI step with `curl`, using a key with the `sandbox:read` scope:\n\n```bash\nSINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)\n./run-signup-test.sh \"ci+${GITHUB_RUN_ID}@example.com\"\n\nfor attempt in 1 2 3 4; do\n  STATUS=$(curl -s -o message.json -w '%{http_code}' -G \\\n    \"https://app.mailyte.com/api/v1/sandbox/inboxes/$INBOX_ID/messages/await\" \\\n    -H \"Authorization: Bearer $MAILYTE_API_KEY\" \\\n    --data-urlencode \"to=ci+${GITHUB_RUN_ID}@example.com\" \\\n    --data-urlencode \"subject=Confirm your email\" \\\n    --data-urlencode \"since=$SINCE\" \\\n    --data-urlencode \"timeout=30\")\n  [ \"$STATUS\" = \"200\" ] && break\n  [ \"$STATUS\" = \"204\" ] || { echo \"await failed: $STATUS\"; cat message.json; exit 1; }\ndone\n\n[ \"$STATUS\" = \"200\" ] || { echo \"no confirmation email in 2 minutes\"; exit 1; }\njq -r '.data.html' message.json | grep -o 'https://app.example.com/confirm/[^\"]*'\n```"
            }
        },
        "/api/v1/sandbox/messages/{id}": {
            "get": {
                "operationId": "getSandboxMessagesId",
                "summary": "Get a sandbox message",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "ULID of the stored message."
                                                        },
                                                        "inbox_id": {
                                                            "type": "string"
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "header_from": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The From header, as written."
                                                        },
                                                        "header_to": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The To header addresses."
                                                        },
                                                        "envelope_rcpts": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "Every address the message was sent to, INCLUDING Bcc: blind recipients are in the envelope, never in the headers, so this is the only place they show."
                                                        },
                                                        "size_bytes": {
                                                            "type": "integer"
                                                        },
                                                        "attachment_count": {
                                                            "type": "integer"
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp",
                                                                "api",
                                                                "inbound"
                                                            ],
                                                            "description": "`api` for a test-mode API key send; `inbound` for mail sent to the inbox's `inbound_address`."
                                                        },
                                                        "simulated_outcome": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "delivered",
                                                                "bounce",
                                                                "softbounce",
                                                                "complaint",
                                                                "suppressed"
                                                            ],
                                                            "description": "The outcome simulated for this message, set by a `@sim.mailyte.com` address or an `X-Mailyte-Simulate` header. Null means the default: accepted, then delivered."
                                                        },
                                                        "spam_score": {
                                                            "type": "number",
                                                            "nullable": true,
                                                            "description": "Null until the message has been scored; scoring runs after it arrives."
                                                        },
                                                        "read_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was marked read. Null means unread."
                                                        },
                                                        "received_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the sandbox accepted it."
                                                        },
                                                        "headers": {
                                                            "type": "array",
                                                            "description": "Every header in order, repeated names included.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "value": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The text/plain part, decoded. Null when there is none."
                                                        },
                                                        "html": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The text/html part, decoded and NOT sanitised: it is exactly what your code sent. Render it only in a sandboxed frame with scripts disabled."
                                                        },
                                                        "attachments": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "index": {
                                                                        "type": "integer",
                                                                        "description": "Pass to GET /sandbox/messages/{id}/attachments/{index}."
                                                                    },
                                                                    "filename": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "content_type": {
                                                                        "type": "string"
                                                                    },
                                                                    "size": {
                                                                        "type": "integer"
                                                                    },
                                                                    "content_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Set for an inline (cid:) part."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "events": {
                                                            "type": "array",
                                                            "description": "The simulated delivery timeline. These exist only in the sandbox: they never reach your suppression list, your live event log or your live webhooks.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "event_type": {
                                                                        "type": "string",
                                                                        "description": "e.g. `email.accepted`, `email.delivered`, `email.bounced`."
                                                                    },
                                                                    "recipient": {
                                                                        "type": "string",
                                                                        "nullable": true
                                                                    },
                                                                    "detail": {
                                                                        "type": "object",
                                                                        "nullable": true,
                                                                        "additionalProperties": true
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "webhook_deliveries": {
                                                            "type": "array",
                                                            "description": "Every sandbox webhook attempt this message caused, with your endpoint's response.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "integer"
                                                                    },
                                                                    "webhook_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The sandbox message that caused it. Null for a `sandbox.test` event."
                                                                    },
                                                                    "event_type": {
                                                                        "type": "string"
                                                                    },
                                                                    "attempt": {
                                                                        "type": "integer",
                                                                        "description": "1 to 5. Retries back off 30 s, 2 min, 5 min, 15 min, 30 min."
                                                                    },
                                                                    "status_code": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Null when no response arrived; see `error`."
                                                                    },
                                                                    "duration_ms": {
                                                                        "type": "integer",
                                                                        "nullable": true
                                                                    },
                                                                    "response_excerpt": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The first 1 KB of your response body."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why no response arrived (timeout, refused, blocked address)."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "description": "When the attempt was made."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "spam": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The spam filter's verdict, as a receiving server would score it. Null until `analysed_at` is set; null after that means scoring was unavailable.",
                                                            "properties": {
                                                                "score": {
                                                                    "type": "number"
                                                                },
                                                                "required_score": {
                                                                    "type": "number",
                                                                    "description": "The score at which mail is treated as spam."
                                                                },
                                                                "action": {
                                                                    "type": "string",
                                                                    "description": "e.g. `no action`, `add header`, `reject`."
                                                                },
                                                                "symbols": {
                                                                    "type": "array",
                                                                    "description": "The rules that fired, largest effect first.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "name": {
                                                                                "type": "string"
                                                                            },
                                                                            "score": {
                                                                                "type": "number"
                                                                            },
                                                                            "description": {
                                                                                "type": "string",
                                                                                "nullable": true
                                                                            },
                                                                            "options": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "checks": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "description": "Problems found in the message, such as a missing text part, images without alt text, insecure links, or no List-Unsubscribe on bulk mail. `[]` means none. Null means it has not been checked yet (see `analysed_at`).",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "severity": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "error",
                                                                            "warning",
                                                                            "info"
                                                                        ]
                                                                    },
                                                                    "title": {
                                                                        "type": "string"
                                                                    },
                                                                    "detail": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "html_support": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "How well the HTML is supported across email clients. Null for a message with no HTML part, before `analysed_at` is set, or if the step failed.",
                                                            "properties": {
                                                                "score_pct": {
                                                                    "type": "integer",
                                                                    "description": "Market-share-weighted share of clients that fully support every feature used."
                                                                },
                                                                "detected_count": {
                                                                    "type": "integer"
                                                                },
                                                                "clients": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "family": {
                                                                                "type": "string"
                                                                            },
                                                                            "support": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "full",
                                                                                    "partial",
                                                                                    "none"
                                                                                ]
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "features": {
                                                                    "type": "array",
                                                                    "description": "Features the message uses that fail or are partial somewhere.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "slug": {
                                                                                "type": "string"
                                                                            },
                                                                            "title": {
                                                                                "type": "string"
                                                                            },
                                                                            "unsupported_in": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                }
                                                                            },
                                                                            "partial_in": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "analysed_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When analysis finished. It runs a few seconds after the message arrives; until then `spam`, `checks` and `html_support` are null."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "The message in full: decoded text and HTML, headers, attachments, the simulated delivery events, and every sandbox webhook attempt it caused with your endpoint's response. The HTML is exactly what your code sent and is not sanitised \u2014 render it only in a sandboxed frame."
            },
            "patch": {
                "operationId": "patchSandboxMessagesId",
                "summary": "Mark a sandbox message read or unread",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "ULID of the stored message."
                                                        },
                                                        "inbox_id": {
                                                            "type": "string"
                                                        },
                                                        "subject": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "header_from": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The From header, as written."
                                                        },
                                                        "header_to": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "The To header addresses."
                                                        },
                                                        "envelope_rcpts": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "Every address the message was sent to, INCLUDING Bcc: blind recipients are in the envelope, never in the headers, so this is the only place they show."
                                                        },
                                                        "size_bytes": {
                                                            "type": "integer"
                                                        },
                                                        "attachment_count": {
                                                            "type": "integer"
                                                        },
                                                        "source": {
                                                            "type": "string",
                                                            "enum": [
                                                                "smtp",
                                                                "api",
                                                                "inbound"
                                                            ],
                                                            "description": "`api` for a test-mode API key send; `inbound` for mail sent to the inbox's `inbound_address`."
                                                        },
                                                        "simulated_outcome": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "delivered",
                                                                "bounce",
                                                                "softbounce",
                                                                "complaint",
                                                                "suppressed"
                                                            ],
                                                            "description": "The outcome simulated for this message, set by a `@sim.mailyte.com` address or an `X-Mailyte-Simulate` header. Null means the default: accepted, then delivered."
                                                        },
                                                        "spam_score": {
                                                            "type": "number",
                                                            "nullable": true,
                                                            "description": "Null until the message has been scored; scoring runs after it arrives."
                                                        },
                                                        "read_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was marked read. Null means unread."
                                                        },
                                                        "received_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When the sandbox accepted it."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "read": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "read": {
                                        "type": "boolean",
                                        "description": "`true` marks the message read, `false` unread.",
                                        "x-example": true
                                    }
                                },
                                "required": [
                                    "read"
                                ]
                            },
                            "example": {
                                "read": true
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteSandboxMessagesId",
                "summary": "Delete a sandbox message",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/sandbox/messages/{id}/raw": {
            "get": {
                "operationId": "getSandboxMessagesIdRaw",
                "summary": "Download a sandbox message as .eml",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The message exactly as it arrived, as a `.eml` download. Bcc recipients are not in it (they never are); read them from `envelope_rcpts`.",
                        "content": {
                            "message/rfc822": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/sandbox/messages/{id}/attachments/{index}": {
            "get": {
                "operationId": "getSandboxMessagesIdAttachmentsIndex",
                "summary": "Download a sandbox message attachment",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "index",
                        "in": "path",
                        "required": true,
                        "description": "The index identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The attachment's bytes, served with its own content type and always as a download.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/sandbox/messages/{id}/events": {
            "post": {
                "operationId": "postSandboxMessagesIdEvents",
                "summary": "Simulate a delivery event on a sandbox message",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "event_type": {
                                                            "type": "string",
                                                            "description": "e.g. `email.accepted`, `email.delivered`, `email.bounced`."
                                                        },
                                                        "recipient": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "detail": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "additionalProperties": true
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Records an open, click, bounce, soft bounce (`deferred`) or complaint on a caught message and fires your sandbox webhooks for it, as `email.opened`, `email.clicked`, `email.bounced`, `email.deferred` or `delivery.complaint` with `environment: \"sandbox\"`. Use it to exercise your webhook handler without a real recipient. `recipient` defaults to the first envelope recipient and must be one of them; `url` is the link reported on a click. Nothing reaches your suppression list or live events.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "event"
                                ],
                                "properties": {
                                    "event": {
                                        "type": "string",
                                        "enum": [
                                            "opened",
                                            "clicked",
                                            "bounced",
                                            "deferred",
                                            "complained"
                                        ],
                                        "description": "Which delivery event to pretend happened.",
                                        "x-example": "opened"
                                    },
                                    "recipient": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "One of the message's envelope recipients."
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "For `clicked`: the link that was clicked.",
                                        "x-example": "https://example.com/webhooks/mailyte"
                                    }
                                }
                            },
                            "example": {
                                "event": "clicked",
                                "url": "https://app.example.com/confirm/abc123"
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/sandbox/webhooks": {
            "get": {
                "operationId": "getSandboxWebhooks",
                "summary": "List sandbox webhooks",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "inbox_id",
                        "in": "query",
                        "required": false,
                        "description": "Only webhooks for this inbox.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "items": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "organization_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "inbox_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The inbox whose messages trigger it. Null means every inbox in your account."
                                                                    },
                                                                    "url": {
                                                                        "type": "string",
                                                                        "format": "uri"
                                                                    },
                                                                    "events": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "email.accepted",
                                                                                "email.delivered",
                                                                                "email.bounced",
                                                                                "email.deferred",
                                                                                "delivery.complaint",
                                                                                "email.dropped",
                                                                                "sandbox.test"
                                                                            ]
                                                                        }
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "active",
                                                                            "disabled"
                                                                        ]
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "description": "When it was created."
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When it was last changed."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Matching rows in all, not just this page."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Sandbox webhooks are separate from your live webhooks: a live webhook never receives a sandbox event and a sandbox webhook never receives a live one. The payload is the same format as live, plus `environment: \"sandbox\"`, `sandbox_inbox_id` and an `X-Webhook-Environment: sandbox` header, so your handler needs no changes and can still tell them apart."
            },
            "post": {
                "operationId": "postSandboxWebhooks",
                "summary": "Create a sandbox webhook",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "organization_id": {
                                                            "type": "string"
                                                        },
                                                        "inbox_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The inbox whose messages trigger it. Null means every inbox in your account."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        },
                                                        "events": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "email.accepted",
                                                                    "email.delivered",
                                                                    "email.bounced",
                                                                    "email.deferred",
                                                                    "delivery.complaint",
                                                                    "email.dropped",
                                                                    "sandbox.test"
                                                                ]
                                                            }
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "disabled"
                                                            ]
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When it was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was last changed."
                                                        },
                                                        "secret": {
                                                            "type": "string",
                                                            "description": "The secret for checking signatures, shown only when the webhook is created. It is separate from your live webhooks' secrets. Sandbox deliveries also carry `environment: \"sandbox\"` and an `X-Webhook-Environment: sandbox` header."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "url": "https://example.com/hooks/mailyte",
                                    "events": [
                                        "email.delivered",
                                        "email.bounced"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Returns the signing `secret` once. Omit `inbox_id` to receive events for every inbox. Addresses on private, loopback or internal networks are refused. Send to a simulator address (`bounce@sim.mailyte.com`, `softbounce@`, `complaint@`, `suppressed@`) to fire the failure events. Owners and admins only.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 2048,
                                        "description": "The full HTTPS address we send to. It must be reachable from the internet.",
                                        "x-example": "https://example.com/webhooks/mailyte"
                                    },
                                    "events": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "email.accepted",
                                                "email.delivered",
                                                "email.bounced",
                                                "email.deferred",
                                                "delivery.complaint",
                                                "email.dropped",
                                                "sandbox.test"
                                            ]
                                        },
                                        "description": "The events to receive. `sandbox.test` is the one `POST /sandbox/webhooks/{id}/test` sends.",
                                        "example": [
                                            "email.delivered",
                                            "email.bounced"
                                        ]
                                    },
                                    "inbox_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. The ID of one Sandbox inbox. Leave it out to cover every inbox.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    }
                                },
                                "required": [
                                    "url",
                                    "events"
                                ]
                            },
                            "example": {
                                "url": "https://example.com/webhooks/mailyte",
                                "events": [
                                    "email.delivered",
                                    "email.bounced"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            }
        },
        "/api/v1/sandbox/webhooks/{id}": {
            "patch": {
                "operationId": "patchSandboxWebhooksId",
                "summary": "Update a sandbox webhook",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "organization_id": {
                                                            "type": "string"
                                                        },
                                                        "inbox_id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The inbox whose messages trigger it. Null means every inbox in your account."
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        },
                                                        "events": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "email.accepted",
                                                                    "email.delivered",
                                                                    "email.bounced",
                                                                    "email.deferred",
                                                                    "delivery.complaint",
                                                                    "email.dropped",
                                                                    "sandbox.test"
                                                                ]
                                                            }
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "active",
                                                                "disabled"
                                                            ]
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When it was created."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When it was last changed."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Change the URL, events, inbox or `status` (`active` / `disabled`). Owners and admins only.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 2048,
                                        "description": "The full HTTPS address we send to. It must be reachable from the internet.",
                                        "x-example": "https://example.com/webhooks/mailyte"
                                    },
                                    "events": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "email.accepted",
                                                "email.delivered",
                                                "email.bounced",
                                                "email.deferred",
                                                "delivery.complaint",
                                                "email.dropped",
                                                "sandbox.test"
                                            ]
                                        },
                                        "description": "The events to receive. Replaces the current list."
                                    },
                                    "status": {
                                        "enum": [
                                            "active",
                                            "disabled"
                                        ],
                                        "type": "string",
                                        "description": "`disabled` stops deliveries; `active` starts them again."
                                    },
                                    "inbox_id": {
                                        "nullable": true,
                                        "type": "string",
                                        "description": "Optional. The ID of one Sandbox inbox. Leave it out to cover every inbox.",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    }
                                }
                            },
                            "example": {
                                "url": "https://example.com/webhooks/mailyte",
                                "events": [
                                    "email.accepted"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "inline-validator",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteSandboxWebhooksId",
                "summary": "Delete a sandbox webhook",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/sandbox/webhooks/{id}/test": {
            "post": {
                "operationId": "postSandboxWebhooksIdTest",
                "summary": "Send a test sandbox webhook",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "queued": {
                                                            "type": "boolean",
                                                            "description": "A `sandbox.test` event is on its way; see the deliveries."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Queues a signed `sandbox.test` event to the endpoint. The attempt appears in the webhook's deliveries. Owners and admins only.\n\nThis endpoint takes no request body.",
                "x-request-body": "none"
            }
        },
        "/api/v1/sandbox/webhooks/{id}/deliveries": {
            "get": {
                "operationId": "getSandboxWebhooksIdDeliveries",
                "summary": "List a sandbox webhook's delivery attempts",
                "tags": [
                    "Sandbox"
                ],
                "x-required-scope": "sandbox:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "At most 100.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "items": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "integer"
                                                                    },
                                                                    "webhook_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The sandbox message that caused it. Null for a `sandbox.test` event."
                                                                    },
                                                                    "event_type": {
                                                                        "type": "string"
                                                                    },
                                                                    "attempt": {
                                                                        "type": "integer",
                                                                        "description": "1 to 5. Retries back off 30 s, 2 min, 5 min, 15 min, 30 min."
                                                                    },
                                                                    "status_code": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Null when no response arrived; see `error`."
                                                                    },
                                                                    "duration_ms": {
                                                                        "type": "integer",
                                                                        "nullable": true
                                                                    },
                                                                    "response_excerpt": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The first 1 KB of your response body."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why no response arrived (timeout, refused, blocked address)."
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "description": "When the attempt was made."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Matching rows in all, not just this page."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Newest first, each with the status code, time taken and the first 1 KB of your endpoint's response."
            }
        },
        "/api/v1/deliverability": {
            "get": {
                "operationId": "getDeliverability",
                "summary": "List deliverabilitys",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "deliverability_report"
                                                            ]
                                                        },
                                                        "score": {
                                                            "type": "integer",
                                                            "description": "0-100."
                                                        },
                                                        "band": {
                                                            "type": "string",
                                                            "enum": [
                                                                "needs_attention",
                                                                "good",
                                                                "excellent"
                                                            ],
                                                            "description": "The score's band, as a fixed value to branch on."
                                                        },
                                                        "window_days": {
                                                            "type": "integer",
                                                            "description": "Everything in this report is computed over this many days, ending now."
                                                        },
                                                        "volume": {
                                                            "type": "object",
                                                            "description": "Counts of what happened.",
                                                            "properties": {
                                                                "submitted": {
                                                                    "type": "integer",
                                                                    "description": "Messages sent. Mail to reserved test domains (.invalid, .test, .example, .localhost, example.com) is not counted here or below."
                                                                },
                                                                "delivered": {
                                                                    "type": "integer",
                                                                    "description": "Distinct MESSAGES delivered, not delivery events."
                                                                },
                                                                "bounced": {
                                                                    "type": "integer",
                                                                    "description": "Messages the recipient's server refused, counted once each. Routing loops are counted separately in `routing_loops`."
                                                                },
                                                                "routing_loops": {
                                                                    "type": "integer",
                                                                    "description": "Messages lost to a mail routing loop (5.4.6). This is a fault on our side, not a bad address: report it to us, and do not remove the contact."
                                                                },
                                                                "opened": {
                                                                    "type": "integer"
                                                                },
                                                                "clicked": {
                                                                    "type": "integer"
                                                                },
                                                                "complaints": {
                                                                    "type": "integer",
                                                                    "description": "`delivery.complaint` events."
                                                                },
                                                                "unsubscribed": {
                                                                    "type": "integer"
                                                                }
                                                            }
                                                        },
                                                        "rates": {
                                                            "type": "object",
                                                            "description": "Percentages from 0 to 100, not fractions: a bounce rate of 50 means half.",
                                                            "properties": {
                                                                "open": {
                                                                    "type": "number"
                                                                },
                                                                "click": {
                                                                    "type": "number"
                                                                },
                                                                "bounce": {
                                                                    "type": "number"
                                                                },
                                                                "negative_engagement": {
                                                                    "type": "number",
                                                                    "description": "Complaints and unsubscribes together."
                                                                }
                                                            }
                                                        },
                                                        "authentication": {
                                                            "type": "object",
                                                            "description": "SPF, DKIM and DMARC for each domain. Domains hidden on the Domains page are left out here, but their mail is still counted in `volume`.",
                                                            "properties": {
                                                                "average_score": {
                                                                    "type": "number",
                                                                    "description": "0-100."
                                                                },
                                                                "domains": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "domain": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "The domain these checks are about."
                                                                            },
                                                                            "score": {
                                                                                "type": "integer",
                                                                                "description": "0-100."
                                                                            },
                                                                            "spf": {
                                                                                "type": "boolean"
                                                                            },
                                                                            "dkim": {
                                                                                "type": "boolean"
                                                                            },
                                                                            "dmarc": {
                                                                                "type": "boolean"
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "recommendations": {
                                                            "type": "array",
                                                            "description": "What to fix, worst first. Empty when there is nothing to say.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "severity": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "critical",
                                                                            "warning",
                                                                            "info"
                                                                        ]
                                                                    },
                                                                    "message": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The advice, for a person to read. Do not match on the text; branch on `severity`."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/reports/email-delivery": {
            "get": {
                "operationId": "getReportsEmailDelivery",
                "summary": "Email Delivery (report)",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "email_delivery_report"
                                                            ]
                                                        },
                                                        "generated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                        },
                                                        "period": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                            "properties": {
                                                                "start_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "end_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "granularity": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "day"
                                                                    ],
                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                }
                                                            }
                                                        },
                                                        "totals": {
                                                            "type": "object",
                                                            "description": "Counts for the whole period. Divide them yourself for rates.",
                                                            "properties": {
                                                                "sent": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Every delivery event in the period: delivered, bounced, deferred, rejected and dropped. It includes deferrals, so it is usually more than the figures beside it added up. Null means unavailable, not 0."
                                                                },
                                                                "delivered": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                },
                                                                "bounced": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages a receiving server refused. Null means unavailable, not 0."
                                                                },
                                                                "failed": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages that will not be delivered: rejected plus dropped. Deferrals are retried and not counted here. Null means unavailable, not 0."
                                                                }
                                                            }
                                                        },
                                                        "series": {
                                                            "type": "array",
                                                            "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "start_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When this time bucket starts: midnight UTC."
                                                                    },
                                                                    "sent": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Every delivery event in the period: delivered, bounced, deferred, rejected and dropped. It includes deferrals, so it is usually more than the figures beside it added up. Null means unavailable, not 0."
                                                                    },
                                                                    "delivered": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                    },
                                                                    "bounced": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Messages a receiving server refused. Null means unavailable, not 0."
                                                                    },
                                                                    "failed": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Messages that will not be delivered: rejected plus dropped. Deferrals are retried and not counted here. Null means unavailable, not 0."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "bounce_reasons": {
                                                            "type": "array",
                                                            "description": "The ten most common bounce reasons in the period, most common first.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "reason": {
                                                                        "type": "string",
                                                                        "description": "The bounce reason as reported. `unknown` groups bounces with no reason, so the counts add up to `totals.bounced`."
                                                                    },
                                                                    "count": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Bounces in the period with this reason. Null means unavailable, not 0."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/reports/engagement": {
            "get": {
                "operationId": "getReportsEngagement",
                "summary": "Engagement (report)",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "engagement_report"
                                                            ]
                                                        },
                                                        "generated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                        },
                                                        "period": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                            "properties": {
                                                                "start_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "end_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "granularity": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "day"
                                                                    ],
                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                }
                                                            }
                                                        },
                                                        "totals": {
                                                            "type": "object",
                                                            "description": "Engagement counts. Divide by `delivered` for rates.",
                                                            "properties": {
                                                                "delivered": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                },
                                                                "opened": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Opens. Each open counts, so one person opening twice counts twice. Null means unavailable, not 0."
                                                                },
                                                                "clicked": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Clicks. Each click counts. Null means unavailable, not 0."
                                                                },
                                                                "unsubscribed": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Unsubscribes. Null means unavailable, not 0."
                                                                }
                                                            }
                                                        },
                                                        "series": {
                                                            "type": "array",
                                                            "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "start_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When this time bucket starts: midnight UTC."
                                                                    },
                                                                    "delivered": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                    },
                                                                    "opened": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Opens. Each open counts, so one person opening twice counts twice. Null means unavailable, not 0."
                                                                    },
                                                                    "clicked": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Clicks. Each click counts. Null means unavailable, not 0."
                                                                    },
                                                                    "unsubscribed": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Unsubscribes. Null means unavailable, not 0."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/reports/domain-health": {
            "get": {
                "operationId": "getReportsDomainHealth",
                "summary": "Domain Health (report)",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "domain_health_report"
                                                            ]
                                                        },
                                                        "generated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                        },
                                                        "period": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Always null: this report shows your domains' DNS as it is now, so `date_range` does not apply.",
                                                            "properties": {
                                                                "start_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "end_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "granularity": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "day"
                                                                    ],
                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                }
                                                            }
                                                        },
                                                        "domains": {
                                                            "type": "array",
                                                            "description": "One row per domain in your organization, soft-deleted domains excluded.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "domain_health"
                                                                        ]
                                                                    },
                                                                    "domain": {
                                                                        "type": "string",
                                                                        "description": "The domain name."
                                                                    },
                                                                    "dns": {
                                                                        "type": "object",
                                                                        "description": "The domain's DNS status.",
                                                                        "properties": {
                                                                            "state": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "verified",
                                                                                    "pending",
                                                                                    "failed",
                                                                                    "unknown"
                                                                                ],
                                                                                "description": "`verified`, `pending`, `failed` or `unknown`."
                                                                            },
                                                                            "verified": {
                                                                                "type": "boolean",
                                                                                "description": "True only for `verified`. `pending` and `failed` are both \"not verified\" to a caller deciding whether to send."
                                                                            }
                                                                        }
                                                                    },
                                                                    "spam_score": {
                                                                        "type": "number",
                                                                        "nullable": true,
                                                                        "description": "Not available yet; always null."
                                                                    },
                                                                    "reputation_score": {
                                                                        "type": "number",
                                                                        "nullable": true,
                                                                        "description": "Always null today, for the same reason as `spam_score`."
                                                                    },
                                                                    "checked_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "Sourced from the domain record's `updated_at`, so it moves whenever anything about the domain changes and is not necessarily when DNS was last checked. Treat it as \"as of\", not as a check timestamp."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "totals": {
                                                            "type": "object",
                                                            "description": "How many domains are in each DNS state. They add up to `domains`. These count domains, not messages.",
                                                            "properties": {
                                                                "domains": {
                                                                    "type": "integer",
                                                                    "description": "Rows in `domains`."
                                                                },
                                                                "verified": {
                                                                    "type": "integer",
                                                                    "description": "Domains whose DNS has passed."
                                                                },
                                                                "pending": {
                                                                    "type": "integer",
                                                                    "description": "Domains whose DNS check has not finished."
                                                                },
                                                                "failed": {
                                                                    "type": "integer",
                                                                    "description": "Domains whose DNS check failed."
                                                                },
                                                                "unknown": {
                                                                    "type": "integer",
                                                                    "description": "Domains whose DNS state is not known."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/reports/volume-trends": {
            "get": {
                "operationId": "getReportsVolumeTrends",
                "summary": "Volume Trends (report)",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "volume_report"
                                                            ]
                                                        },
                                                        "generated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                        },
                                                        "period": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                            "properties": {
                                                                "start_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "end_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "granularity": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "day"
                                                                    ],
                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                }
                                                            }
                                                        },
                                                        "totals": {
                                                            "type": "object",
                                                            "description": "The totals for the period.",
                                                            "properties": {
                                                                "events": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                },
                                                                "sent": {
                                                                    "type": "integer",
                                                                    "nullable": false,
                                                                    "description": "Messages delivered plus bounced. This is narrower than `sent` in `/reports/email-delivery`, so do not compare the two."
                                                                },
                                                                "received": {
                                                                    "type": "integer",
                                                                    "nullable": false,
                                                                    "description": "Inbound mail (`email.inbound`). Summed from `series`."
                                                                }
                                                            }
                                                        },
                                                        "series": {
                                                            "type": "array",
                                                            "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "start_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When this time bucket starts: midnight UTC."
                                                                    },
                                                                    "events": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                    },
                                                                    "sent": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Messages delivered plus bounced in this bucket. This is narrower than `sent` in `/reports/email-delivery`, so do not compare the two. Null means unavailable, not 0."
                                                                    },
                                                                    "received": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "Incoming mail. Null means unavailable, not 0."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "distributions": {
                                                            "type": "object",
                                                            "description": "Activity by hour of day and by weekday. An hour or day with no events is left out rather than shown as 0. Times are in the server's time zone.",
                                                            "properties": {
                                                                "hour_of_day": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "bucket": {
                                                                                "type": "string",
                                                                                "description": "`\"00\"` to `\"23\"`."
                                                                            },
                                                                            "events": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                "day_of_week": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "bucket": {
                                                                                "type": "string",
                                                                                "description": "`\"Monday\"` to `\"Sunday\"`, in English."
                                                                            },
                                                                            "events": {
                                                                                "type": "integer",
                                                                                "nullable": true,
                                                                                "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/reports/security": {
            "get": {
                "operationId": "getReportsSecurity",
                "summary": "Security (report)",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "security_report"
                                                            ]
                                                        },
                                                        "generated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                        },
                                                        "period": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Null while `availability.state` is `unavailable`, which is every response today: there is no window because nothing was measured over one.",
                                                            "properties": {
                                                                "start_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "end_at": {
                                                                    "type": "string",
                                                                    "format": "date-time"
                                                                },
                                                                "granularity": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "day"
                                                                    ],
                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                }
                                                            }
                                                        },
                                                        "availability": {
                                                            "type": "object",
                                                            "description": "Whether this report has data. Check it before reading `totals`.",
                                                            "properties": {
                                                                "state": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "available",
                                                                        "unavailable"
                                                                    ],
                                                                    "description": "Today always `unavailable`. No spam, malware or phishing detection data source exists yet in mailyte-api or the mail server."
                                                                },
                                                                "reason": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "Why the figures are unavailable. Null when they are not."
                                                                }
                                                            }
                                                        },
                                                        "totals": {
                                                            "type": "object",
                                                            "description": "Not available yet: every count is null, which means not measured, not 0.",
                                                            "properties": {
                                                                "scanned": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages checked for spam, malware and phishing. Null means unavailable, not 0."
                                                                },
                                                                "spam": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages found to be spam. Null means unavailable, not 0."
                                                                },
                                                                "malware": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages found to carry malware. Null means unavailable, not 0."
                                                                },
                                                                "phishing": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Messages found to be phishing. Null means unavailable, not 0."
                                                                }
                                                            }
                                                        },
                                                        "series": {
                                                            "type": "array",
                                                            "nullable": true,
                                                            "description": "Null while `availability.state` is `unavailable`.",
                                                            "items": {
                                                                "type": "object"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/reports/history": {
            "get": {
                "operationId": "getReportsHistory",
                "summary": "History (report)",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "object": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "report_generation"
                                                                        ]
                                                                    },
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "The report's ID, a ULID. The same ID is returned by `POST /reports/generate`."
                                                                    },
                                                                    "template_id": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "email-delivery",
                                                                            "domain-health",
                                                                            "engagement",
                                                                            "volume-trends",
                                                                            "security"
                                                                        ],
                                                                        "description": "Matches the `id` of a row from `GET /reports/templates`. Note `security` is accepted here but is not advertised by that endpoint."
                                                                    },
                                                                    "format": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "pdf",
                                                                            "csv",
                                                                            "json"
                                                                        ],
                                                                        "description": "The format you asked for. Reports are stored as JSON for now; PDF and CSV are not available yet."
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "pending",
                                                                            "processing",
                                                                            "completed",
                                                                            "failed"
                                                                        ],
                                                                        "description": "Where the report is: poll until it is `completed` or `failed`."
                                                                    },
                                                                    "parameters": {
                                                                        "type": "object",
                                                                        "additionalProperties": true,
                                                                        "description": "The settings the report was asked for with. Always an object."
                                                                    },
                                                                    "error": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "Why the report failed. Set only when `status` is `failed`."
                                                                    },
                                                                    "result": {
                                                                        "nullable": true,
                                                                        "description": "The report, in the same shape as the live endpoint. Null while it is being made, when it failed, or for a report type without a live endpoint. Its `period` is always null.",
                                                                        "oneOf": [
                                                                            {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "object": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "email_delivery_report"
                                                                                        ]
                                                                                    },
                                                                                    "generated_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                                    },
                                                                                    "period": {
                                                                                        "type": "object",
                                                                                        "nullable": true,
                                                                                        "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                                                        "properties": {
                                                                                            "start_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "end_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "granularity": {
                                                                                                "type": "string",
                                                                                                "enum": [
                                                                                                    "day"
                                                                                                ],
                                                                                                "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "totals": {
                                                                                        "type": "object",
                                                                                        "description": "Counts for the whole period. Divide them yourself for rates.",
                                                                                        "properties": {
                                                                                            "sent": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Every delivery event in the period: delivered, bounced, deferred, rejected and dropped. It includes deferrals, so it is usually more than the figures beside it added up. Null means unavailable, not 0."
                                                                                            },
                                                                                            "delivered": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                                            },
                                                                                            "bounced": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Messages a receiving server refused. Null means unavailable, not 0."
                                                                                            },
                                                                                            "failed": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Messages that will not be delivered: rejected plus dropped. Deferrals are retried and not counted here. Null means unavailable, not 0."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "series": {
                                                                                        "type": "array",
                                                                                        "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "properties": {
                                                                                                "start_at": {
                                                                                                    "type": "string",
                                                                                                    "format": "date-time",
                                                                                                    "nullable": true,
                                                                                                    "description": "When this time bucket starts: midnight UTC."
                                                                                                },
                                                                                                "sent": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Every delivery event in the period: delivered, bounced, deferred, rejected and dropped. It includes deferrals, so it is usually more than the figures beside it added up. Null means unavailable, not 0."
                                                                                                },
                                                                                                "delivered": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                                                },
                                                                                                "bounced": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Messages a receiving server refused. Null means unavailable, not 0."
                                                                                                },
                                                                                                "failed": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Messages that will not be delivered: rejected plus dropped. Deferrals are retried and not counted here. Null means unavailable, not 0."
                                                                                                }
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "bounce_reasons": {
                                                                                        "type": "array",
                                                                                        "description": "The ten most common bounce reasons in the period, most common first.",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "properties": {
                                                                                                "reason": {
                                                                                                    "type": "string",
                                                                                                    "description": "The bounce reason as reported. `unknown` groups bounces with no reason, so the counts add up to `totals.bounced`."
                                                                                                },
                                                                                                "count": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Bounces in the period with this reason. Null means unavailable, not 0."
                                                                                                }
                                                                                            }
                                                                                        }
                                                                                    }
                                                                                }
                                                                            },
                                                                            {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "object": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "engagement_report"
                                                                                        ]
                                                                                    },
                                                                                    "generated_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                                    },
                                                                                    "period": {
                                                                                        "type": "object",
                                                                                        "nullable": true,
                                                                                        "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                                                        "properties": {
                                                                                            "start_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "end_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "granularity": {
                                                                                                "type": "string",
                                                                                                "enum": [
                                                                                                    "day"
                                                                                                ],
                                                                                                "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "totals": {
                                                                                        "type": "object",
                                                                                        "description": "Engagement counts. Divide by `delivered` for rates.",
                                                                                        "properties": {
                                                                                            "delivered": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                                            },
                                                                                            "opened": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Opens. Each open counts, so one person opening twice counts twice. Null means unavailable, not 0."
                                                                                            },
                                                                                            "clicked": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Clicks. Each click counts. Null means unavailable, not 0."
                                                                                            },
                                                                                            "unsubscribed": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Unsubscribes. Null means unavailable, not 0."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "series": {
                                                                                        "type": "array",
                                                                                        "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "properties": {
                                                                                                "start_at": {
                                                                                                    "type": "string",
                                                                                                    "format": "date-time",
                                                                                                    "nullable": true,
                                                                                                    "description": "When this time bucket starts: midnight UTC."
                                                                                                },
                                                                                                "delivered": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                                                },
                                                                                                "opened": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Opens. Each open counts, so one person opening twice counts twice. Null means unavailable, not 0."
                                                                                                },
                                                                                                "clicked": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Clicks. Each click counts. Null means unavailable, not 0."
                                                                                                },
                                                                                                "unsubscribed": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Unsubscribes. Null means unavailable, not 0."
                                                                                                }
                                                                                            }
                                                                                        }
                                                                                    }
                                                                                }
                                                                            },
                                                                            {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "object": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "domain_health_report"
                                                                                        ]
                                                                                    },
                                                                                    "generated_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                                    },
                                                                                    "period": {
                                                                                        "type": "object",
                                                                                        "nullable": true,
                                                                                        "description": "Always null: this report shows your domains' DNS as it is now, so `date_range` does not apply.",
                                                                                        "properties": {
                                                                                            "start_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "end_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "granularity": {
                                                                                                "type": "string",
                                                                                                "enum": [
                                                                                                    "day"
                                                                                                ],
                                                                                                "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "domains": {
                                                                                        "type": "array",
                                                                                        "description": "One row per domain in your organization, soft-deleted domains excluded.",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "properties": {
                                                                                                "object": {
                                                                                                    "type": "string",
                                                                                                    "enum": [
                                                                                                        "domain_health"
                                                                                                    ]
                                                                                                },
                                                                                                "domain": {
                                                                                                    "type": "string",
                                                                                                    "description": "The domain name."
                                                                                                },
                                                                                                "dns": {
                                                                                                    "type": "object",
                                                                                                    "description": "The domain's DNS status.",
                                                                                                    "properties": {
                                                                                                        "state": {
                                                                                                            "type": "string",
                                                                                                            "enum": [
                                                                                                                "verified",
                                                                                                                "pending",
                                                                                                                "failed",
                                                                                                                "unknown"
                                                                                                            ],
                                                                                                            "description": "`verified`, `pending`, `failed` or `unknown`."
                                                                                                        },
                                                                                                        "verified": {
                                                                                                            "type": "boolean",
                                                                                                            "description": "True only for `verified`. `pending` and `failed` are both \"not verified\" to a caller deciding whether to send."
                                                                                                        }
                                                                                                    }
                                                                                                },
                                                                                                "spam_score": {
                                                                                                    "type": "number",
                                                                                                    "nullable": true,
                                                                                                    "description": "Not available yet; always null."
                                                                                                },
                                                                                                "reputation_score": {
                                                                                                    "type": "number",
                                                                                                    "nullable": true,
                                                                                                    "description": "Always null today, for the same reason as `spam_score`."
                                                                                                },
                                                                                                "checked_at": {
                                                                                                    "type": "string",
                                                                                                    "format": "date-time",
                                                                                                    "nullable": true,
                                                                                                    "description": "Sourced from the domain record's `updated_at`, so it moves whenever anything about the domain changes and is not necessarily when DNS was last checked. Treat it as \"as of\", not as a check timestamp."
                                                                                                }
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "totals": {
                                                                                        "type": "object",
                                                                                        "description": "How many domains are in each DNS state. They add up to `domains`. These count domains, not messages.",
                                                                                        "properties": {
                                                                                            "domains": {
                                                                                                "type": "integer",
                                                                                                "description": "Rows in `domains`."
                                                                                            },
                                                                                            "verified": {
                                                                                                "type": "integer",
                                                                                                "description": "Domains whose DNS has passed."
                                                                                            },
                                                                                            "pending": {
                                                                                                "type": "integer",
                                                                                                "description": "Domains whose DNS check has not finished."
                                                                                            },
                                                                                            "failed": {
                                                                                                "type": "integer",
                                                                                                "description": "Domains whose DNS check failed."
                                                                                            },
                                                                                            "unknown": {
                                                                                                "type": "integer",
                                                                                                "description": "Domains whose DNS state is not known."
                                                                                            }
                                                                                        }
                                                                                    }
                                                                                }
                                                                            },
                                                                            {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "object": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "volume_report"
                                                                                        ]
                                                                                    },
                                                                                    "generated_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                                    },
                                                                                    "period": {
                                                                                        "type": "object",
                                                                                        "nullable": true,
                                                                                        "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                                                        "properties": {
                                                                                            "start_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "end_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "granularity": {
                                                                                                "type": "string",
                                                                                                "enum": [
                                                                                                    "day"
                                                                                                ],
                                                                                                "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "totals": {
                                                                                        "type": "object",
                                                                                        "description": "The totals for the period.",
                                                                                        "properties": {
                                                                                            "events": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                                            },
                                                                                            "sent": {
                                                                                                "type": "integer",
                                                                                                "nullable": false,
                                                                                                "description": "Messages delivered plus bounced. This is narrower than `sent` in `/reports/email-delivery`, so do not compare the two."
                                                                                            },
                                                                                            "received": {
                                                                                                "type": "integer",
                                                                                                "nullable": false,
                                                                                                "description": "Inbound mail (`email.inbound`). Summed from `series`."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "series": {
                                                                                        "type": "array",
                                                                                        "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                                                        "items": {
                                                                                            "type": "object",
                                                                                            "properties": {
                                                                                                "start_at": {
                                                                                                    "type": "string",
                                                                                                    "format": "date-time",
                                                                                                    "nullable": true,
                                                                                                    "description": "When this time bucket starts: midnight UTC."
                                                                                                },
                                                                                                "events": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                                                },
                                                                                                "sent": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Messages delivered plus bounced in this bucket. This is narrower than `sent` in `/reports/email-delivery`, so do not compare the two. Null means unavailable, not 0."
                                                                                                },
                                                                                                "received": {
                                                                                                    "type": "integer",
                                                                                                    "nullable": true,
                                                                                                    "description": "Incoming mail. Null means unavailable, not 0."
                                                                                                }
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "distributions": {
                                                                                        "type": "object",
                                                                                        "description": "Activity by hour of day and by weekday. An hour or day with no events is left out rather than shown as 0. Times are in the server's time zone.",
                                                                                        "properties": {
                                                                                            "hour_of_day": {
                                                                                                "type": "array",
                                                                                                "items": {
                                                                                                    "type": "object",
                                                                                                    "properties": {
                                                                                                        "bucket": {
                                                                                                            "type": "string",
                                                                                                            "description": "`\"00\"` to `\"23\"`."
                                                                                                        },
                                                                                                        "events": {
                                                                                                            "type": "integer",
                                                                                                            "nullable": true,
                                                                                                            "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                                                        }
                                                                                                    }
                                                                                                }
                                                                                            },
                                                                                            "day_of_week": {
                                                                                                "type": "array",
                                                                                                "items": {
                                                                                                    "type": "object",
                                                                                                    "properties": {
                                                                                                        "bucket": {
                                                                                                            "type": "string",
                                                                                                            "description": "`\"Monday\"` to `\"Sunday\"`, in English."
                                                                                                        },
                                                                                                        "events": {
                                                                                                            "type": "integer",
                                                                                                            "nullable": true,
                                                                                                            "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                                                        }
                                                                                                    }
                                                                                                }
                                                                                            }
                                                                                        }
                                                                                    }
                                                                                }
                                                                            },
                                                                            {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "object": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "security_report"
                                                                                        ]
                                                                                    },
                                                                                    "generated_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                                    },
                                                                                    "period": {
                                                                                        "type": "object",
                                                                                        "nullable": true,
                                                                                        "description": "Null while `availability.state` is `unavailable`, which is every response today: there is no window because nothing was measured over one.",
                                                                                        "properties": {
                                                                                            "start_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "end_at": {
                                                                                                "type": "string",
                                                                                                "format": "date-time"
                                                                                            },
                                                                                            "granularity": {
                                                                                                "type": "string",
                                                                                                "enum": [
                                                                                                    "day"
                                                                                                ],
                                                                                                "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "availability": {
                                                                                        "type": "object",
                                                                                        "description": "Whether this report has data. Check it before reading `totals`.",
                                                                                        "properties": {
                                                                                            "state": {
                                                                                                "type": "string",
                                                                                                "enum": [
                                                                                                    "available",
                                                                                                    "unavailable"
                                                                                                ],
                                                                                                "description": "Today always `unavailable`. No spam, malware or phishing detection data source exists yet in mailyte-api or the mail server."
                                                                                            },
                                                                                            "reason": {
                                                                                                "type": "string",
                                                                                                "nullable": true,
                                                                                                "description": "Why the figures are unavailable. Null when they are not."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "totals": {
                                                                                        "type": "object",
                                                                                        "description": "Not available yet: every count is null, which means not measured, not 0.",
                                                                                        "properties": {
                                                                                            "scanned": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Messages checked for spam, malware and phishing. Null means unavailable, not 0."
                                                                                            },
                                                                                            "spam": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Messages found to be spam. Null means unavailable, not 0."
                                                                                            },
                                                                                            "malware": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Messages found to carry malware. Null means unavailable, not 0."
                                                                                            },
                                                                                            "phishing": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Messages found to be phishing. Null means unavailable, not 0."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "series": {
                                                                                        "type": "array",
                                                                                        "nullable": true,
                                                                                        "description": "Null while `availability.state` is `unavailable`.",
                                                                                        "items": {
                                                                                            "type": "object"
                                                                                        }
                                                                                    }
                                                                                }
                                                                            }
                                                                        ]
                                                                    },
                                                                    "requested_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the report was asked for."
                                                                    },
                                                                    "completed_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the report finished. Set only when it succeeded; read `status` to tell a running report from a failed one."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination_meta": {
                                                            "$ref": "#/components/schemas/PaginationMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/reports/templates": {
            "get": {
                "operationId": "getReportsTemplates",
                "summary": "Templates (report)",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "report_template"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "email-delivery",
                                                                    "domain-health",
                                                                    "engagement",
                                                                    "volume-trends"
                                                                ],
                                                                "description": "The value to send as `template_id` to `POST /reports/generate`. That endpoint also accepts `security`, which is not listed here."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "The report's name."
                                                            },
                                                            "description": {
                                                                "type": "string",
                                                                "description": "One line about the report."
                                                            },
                                                            "parameters": {
                                                                "type": "array",
                                                                "description": "What this report accepts in `parameters` on `POST /reports/generate`. `[]` means it takes none.",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "name": {
                                                                            "type": "string",
                                                                            "description": "The key to send in `parameters`."
                                                                        },
                                                                        "type": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "string"
                                                                            ],
                                                                            "description": "The value's type; always `string` today. `date_range` takes `day`, `week`, `month` or `quarter`; anything else falls back to `month`."
                                                                        },
                                                                        "required": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "default": {
                                                                            "nullable": true,
                                                                            "description": "What is used when you leave the parameter out. Null when it has no default."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/reports/generate": {
            "post": {
                "operationId": "postReportsGenerate",
                "summary": "Generate (report)",
                "tags": [
                    "Reports"
                ],
                "x-required-scope": "reports:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "report_generation"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "The report's ID, a ULID. The same ID is returned by `POST /reports/generate`."
                                                        },
                                                        "template_id": {
                                                            "type": "string",
                                                            "enum": [
                                                                "email-delivery",
                                                                "domain-health",
                                                                "engagement",
                                                                "volume-trends",
                                                                "security"
                                                            ],
                                                            "description": "Matches the `id` of a row from `GET /reports/templates`. Note `security` is accepted here but is not advertised by that endpoint."
                                                        },
                                                        "format": {
                                                            "type": "string",
                                                            "enum": [
                                                                "pdf",
                                                                "csv",
                                                                "json"
                                                            ],
                                                            "description": "The format you asked for. Reports are stored as JSON for now; PDF and CSV are not available yet."
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "pending",
                                                                "processing",
                                                                "completed",
                                                                "failed"
                                                            ],
                                                            "description": "Where the report is: poll until it is `completed` or `failed`."
                                                        },
                                                        "parameters": {
                                                            "type": "object",
                                                            "additionalProperties": true,
                                                            "description": "The settings the report was asked for with. Always an object."
                                                        },
                                                        "error": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Why the report failed. Set only when `status` is `failed`."
                                                        },
                                                        "result": {
                                                            "nullable": true,
                                                            "description": "The report, in the same shape as the live endpoint. Null while it is being made, when it failed, or for a report type without a live endpoint. Its `period` is always null.",
                                                            "oneOf": [
                                                                {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "object": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "email_delivery_report"
                                                                            ]
                                                                        },
                                                                        "generated_at": {
                                                                            "type": "string",
                                                                            "format": "date-time",
                                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                        },
                                                                        "period": {
                                                                            "type": "object",
                                                                            "nullable": true,
                                                                            "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                                            "properties": {
                                                                                "start_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "end_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "granularity": {
                                                                                    "type": "string",
                                                                                    "enum": [
                                                                                        "day"
                                                                                    ],
                                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                }
                                                                            }
                                                                        },
                                                                        "totals": {
                                                                            "type": "object",
                                                                            "description": "Counts for the whole period. Divide them yourself for rates.",
                                                                            "properties": {
                                                                                "sent": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Every delivery event in the period: delivered, bounced, deferred, rejected and dropped. It includes deferrals, so it is usually more than the figures beside it added up. Null means unavailable, not 0."
                                                                                },
                                                                                "delivered": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                                },
                                                                                "bounced": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Messages a receiving server refused. Null means unavailable, not 0."
                                                                                },
                                                                                "failed": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Messages that will not be delivered: rejected plus dropped. Deferrals are retried and not counted here. Null means unavailable, not 0."
                                                                                }
                                                                            }
                                                                        },
                                                                        "series": {
                                                                            "type": "array",
                                                                            "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "start_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "nullable": true,
                                                                                        "description": "When this time bucket starts: midnight UTC."
                                                                                    },
                                                                                    "sent": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Every delivery event in the period: delivered, bounced, deferred, rejected and dropped. It includes deferrals, so it is usually more than the figures beside it added up. Null means unavailable, not 0."
                                                                                    },
                                                                                    "delivered": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                                    },
                                                                                    "bounced": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Messages a receiving server refused. Null means unavailable, not 0."
                                                                                    },
                                                                                    "failed": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Messages that will not be delivered: rejected plus dropped. Deferrals are retried and not counted here. Null means unavailable, not 0."
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "bounce_reasons": {
                                                                            "type": "array",
                                                                            "description": "The ten most common bounce reasons in the period, most common first.",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "reason": {
                                                                                        "type": "string",
                                                                                        "description": "The bounce reason as reported. `unknown` groups bounces with no reason, so the counts add up to `totals.bounced`."
                                                                                    },
                                                                                    "count": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Bounces in the period with this reason. Null means unavailable, not 0."
                                                                                    }
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "object": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "engagement_report"
                                                                            ]
                                                                        },
                                                                        "generated_at": {
                                                                            "type": "string",
                                                                            "format": "date-time",
                                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                        },
                                                                        "period": {
                                                                            "type": "object",
                                                                            "nullable": true,
                                                                            "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                                            "properties": {
                                                                                "start_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "end_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "granularity": {
                                                                                    "type": "string",
                                                                                    "enum": [
                                                                                        "day"
                                                                                    ],
                                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                }
                                                                            }
                                                                        },
                                                                        "totals": {
                                                                            "type": "object",
                                                                            "description": "Engagement counts. Divide by `delivered` for rates.",
                                                                            "properties": {
                                                                                "delivered": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                                },
                                                                                "opened": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Opens. Each open counts, so one person opening twice counts twice. Null means unavailable, not 0."
                                                                                },
                                                                                "clicked": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Clicks. Each click counts. Null means unavailable, not 0."
                                                                                },
                                                                                "unsubscribed": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Unsubscribes. Null means unavailable, not 0."
                                                                                }
                                                                            }
                                                                        },
                                                                        "series": {
                                                                            "type": "array",
                                                                            "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "start_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "nullable": true,
                                                                                        "description": "When this time bucket starts: midnight UTC."
                                                                                    },
                                                                                    "delivered": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Messages a receiving server accepted. Divide engagement counts by this for rates. Null means unavailable, not 0."
                                                                                    },
                                                                                    "opened": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Opens. Each open counts, so one person opening twice counts twice. Null means unavailable, not 0."
                                                                                    },
                                                                                    "clicked": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Clicks. Each click counts. Null means unavailable, not 0."
                                                                                    },
                                                                                    "unsubscribed": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Unsubscribes. Null means unavailable, not 0."
                                                                                    }
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "object": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "domain_health_report"
                                                                            ]
                                                                        },
                                                                        "generated_at": {
                                                                            "type": "string",
                                                                            "format": "date-time",
                                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                        },
                                                                        "period": {
                                                                            "type": "object",
                                                                            "nullable": true,
                                                                            "description": "Always null: this report shows your domains' DNS as it is now, so `date_range` does not apply.",
                                                                            "properties": {
                                                                                "start_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "end_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "granularity": {
                                                                                    "type": "string",
                                                                                    "enum": [
                                                                                        "day"
                                                                                    ],
                                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                }
                                                                            }
                                                                        },
                                                                        "domains": {
                                                                            "type": "array",
                                                                            "description": "One row per domain in your organization, soft-deleted domains excluded.",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "object": {
                                                                                        "type": "string",
                                                                                        "enum": [
                                                                                            "domain_health"
                                                                                        ]
                                                                                    },
                                                                                    "domain": {
                                                                                        "type": "string",
                                                                                        "description": "The domain name."
                                                                                    },
                                                                                    "dns": {
                                                                                        "type": "object",
                                                                                        "description": "The domain's DNS status.",
                                                                                        "properties": {
                                                                                            "state": {
                                                                                                "type": "string",
                                                                                                "enum": [
                                                                                                    "verified",
                                                                                                    "pending",
                                                                                                    "failed",
                                                                                                    "unknown"
                                                                                                ],
                                                                                                "description": "`verified`, `pending`, `failed` or `unknown`."
                                                                                            },
                                                                                            "verified": {
                                                                                                "type": "boolean",
                                                                                                "description": "True only for `verified`. `pending` and `failed` are both \"not verified\" to a caller deciding whether to send."
                                                                                            }
                                                                                        }
                                                                                    },
                                                                                    "spam_score": {
                                                                                        "type": "number",
                                                                                        "nullable": true,
                                                                                        "description": "Not available yet; always null."
                                                                                    },
                                                                                    "reputation_score": {
                                                                                        "type": "number",
                                                                                        "nullable": true,
                                                                                        "description": "Always null today, for the same reason as `spam_score`."
                                                                                    },
                                                                                    "checked_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "nullable": true,
                                                                                        "description": "Sourced from the domain record's `updated_at`, so it moves whenever anything about the domain changes and is not necessarily when DNS was last checked. Treat it as \"as of\", not as a check timestamp."
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "totals": {
                                                                            "type": "object",
                                                                            "description": "How many domains are in each DNS state. They add up to `domains`. These count domains, not messages.",
                                                                            "properties": {
                                                                                "domains": {
                                                                                    "type": "integer",
                                                                                    "description": "Rows in `domains`."
                                                                                },
                                                                                "verified": {
                                                                                    "type": "integer",
                                                                                    "description": "Domains whose DNS has passed."
                                                                                },
                                                                                "pending": {
                                                                                    "type": "integer",
                                                                                    "description": "Domains whose DNS check has not finished."
                                                                                },
                                                                                "failed": {
                                                                                    "type": "integer",
                                                                                    "description": "Domains whose DNS check failed."
                                                                                },
                                                                                "unknown": {
                                                                                    "type": "integer",
                                                                                    "description": "Domains whose DNS state is not known."
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "object": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "volume_report"
                                                                            ]
                                                                        },
                                                                        "generated_at": {
                                                                            "type": "string",
                                                                            "format": "date-time",
                                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                        },
                                                                        "period": {
                                                                            "type": "object",
                                                                            "nullable": true,
                                                                            "description": "The period this report covers. A `date_range` other than `day`, `week`, `month` or `quarter` falls back to `month`, and this shows it. Null for a report read from `/reports/history`.",
                                                                            "properties": {
                                                                                "start_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "end_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "granularity": {
                                                                                    "type": "string",
                                                                                    "enum": [
                                                                                        "day"
                                                                                    ],
                                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                }
                                                                            }
                                                                        },
                                                                        "totals": {
                                                                            "type": "object",
                                                                            "description": "The totals for the period.",
                                                                            "properties": {
                                                                                "events": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                                },
                                                                                "sent": {
                                                                                    "type": "integer",
                                                                                    "nullable": false,
                                                                                    "description": "Messages delivered plus bounced. This is narrower than `sent` in `/reports/email-delivery`, so do not compare the two."
                                                                                },
                                                                                "received": {
                                                                                    "type": "integer",
                                                                                    "nullable": false,
                                                                                    "description": "Inbound mail (`email.inbound`). Summed from `series`."
                                                                                }
                                                                            }
                                                                        },
                                                                        "series": {
                                                                            "type": "array",
                                                                            "description": "The same counts bucketed over the period, oldest first. Rows are SPARSE: a bucket in which nothing happened has no row at all, rather than a row of zeros, so do not index this array by day offset.",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "start_at": {
                                                                                        "type": "string",
                                                                                        "format": "date-time",
                                                                                        "nullable": true,
                                                                                        "description": "When this time bucket starts: midnight UTC."
                                                                                    },
                                                                                    "events": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                                    },
                                                                                    "sent": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Messages delivered plus bounced in this bucket. This is narrower than `sent` in `/reports/email-delivery`, so do not compare the two. Null means unavailable, not 0."
                                                                                    },
                                                                                    "received": {
                                                                                        "type": "integer",
                                                                                        "nullable": true,
                                                                                        "description": "Incoming mail. Null means unavailable, not 0."
                                                                                    }
                                                                                }
                                                                            }
                                                                        },
                                                                        "distributions": {
                                                                            "type": "object",
                                                                            "description": "Activity by hour of day and by weekday. An hour or day with no events is left out rather than shown as 0. Times are in the server's time zone.",
                                                                            "properties": {
                                                                                "hour_of_day": {
                                                                                    "type": "array",
                                                                                    "items": {
                                                                                        "type": "object",
                                                                                        "properties": {
                                                                                            "bucket": {
                                                                                                "type": "string",
                                                                                                "description": "`\"00\"` to `\"23\"`."
                                                                                            },
                                                                                            "events": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                                            }
                                                                                        }
                                                                                    }
                                                                                },
                                                                                "day_of_week": {
                                                                                    "type": "array",
                                                                                    "items": {
                                                                                        "type": "object",
                                                                                        "properties": {
                                                                                            "bucket": {
                                                                                                "type": "string",
                                                                                                "description": "`\"Monday\"` to `\"Sunday\"`, in English."
                                                                                            },
                                                                                            "events": {
                                                                                                "type": "integer",
                                                                                                "nullable": true,
                                                                                                "description": "Every event in the period, including opens, clicks and unsubscribes, so it is not a count of messages. Null means unavailable, not 0."
                                                                                            }
                                                                                        }
                                                                                    }
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                },
                                                                {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "object": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "security_report"
                                                                            ]
                                                                        },
                                                                        "generated_at": {
                                                                            "type": "string",
                                                                            "format": "date-time",
                                                                            "description": "When this response was computed, ISO 8601 UTC. Every report answers it, so \"is this figure stale?\" never depends on which report you asked."
                                                                        },
                                                                        "period": {
                                                                            "type": "object",
                                                                            "nullable": true,
                                                                            "description": "Null while `availability.state` is `unavailable`, which is every response today: there is no window because nothing was measured over one.",
                                                                            "properties": {
                                                                                "start_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "end_at": {
                                                                                    "type": "string",
                                                                                    "format": "date-time"
                                                                                },
                                                                                "granularity": {
                                                                                    "type": "string",
                                                                                    "enum": [
                                                                                        "day"
                                                                                    ],
                                                                                    "description": "The width of one `series` bucket. Always `day`: the `granularity` query parameter is accepted and ignored."
                                                                                }
                                                                            }
                                                                        },
                                                                        "availability": {
                                                                            "type": "object",
                                                                            "description": "Whether this report has data. Check it before reading `totals`.",
                                                                            "properties": {
                                                                                "state": {
                                                                                    "type": "string",
                                                                                    "enum": [
                                                                                        "available",
                                                                                        "unavailable"
                                                                                    ],
                                                                                    "description": "Today always `unavailable`. No spam, malware or phishing detection data source exists yet in mailyte-api or the mail server."
                                                                                },
                                                                                "reason": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "description": "Why the figures are unavailable. Null when they are not."
                                                                                }
                                                                            }
                                                                        },
                                                                        "totals": {
                                                                            "type": "object",
                                                                            "description": "Not available yet: every count is null, which means not measured, not 0.",
                                                                            "properties": {
                                                                                "scanned": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Messages checked for spam, malware and phishing. Null means unavailable, not 0."
                                                                                },
                                                                                "spam": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Messages found to be spam. Null means unavailable, not 0."
                                                                                },
                                                                                "malware": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Messages found to carry malware. Null means unavailable, not 0."
                                                                                },
                                                                                "phishing": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Messages found to be phishing. Null means unavailable, not 0."
                                                                                }
                                                                            }
                                                                        },
                                                                        "series": {
                                                                            "type": "array",
                                                                            "nullable": true,
                                                                            "description": "Null while `availability.state` is `unavailable`.",
                                                                            "items": {
                                                                                "type": "object"
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            ]
                                                        },
                                                        "requested_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the report was asked for."
                                                        },
                                                        "completed_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the report finished. Set only when it succeeded; read `status` to tell a running report from a failed one."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "template_id": {
                                        "type": "string",
                                        "enum": [
                                            "email-delivery",
                                            "domain-health",
                                            "engagement",
                                            "volume-trends",
                                            "security"
                                        ],
                                        "description": "Which report: delivery, domain health, engagement, volume over time or security.",
                                        "example": "email-delivery",
                                        "x-example": "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                    },
                                    "format": {
                                        "type": "string",
                                        "enum": [
                                            "pdf",
                                            "csv",
                                            "json"
                                        ],
                                        "description": "The file type of the report.",
                                        "x-example": "pdf"
                                    },
                                    "parameters": {
                                        "type": "object",
                                        "additionalProperties": true,
                                        "description": "Optional. Extra settings for this kind of report, as `GET /reports/templates` lists them; for example `{\"granularity\": \"day\"}` on `volume-trends`."
                                    },
                                    "date_range": {
                                        "type": "object",
                                        "properties": {
                                            "start": {
                                                "type": "string",
                                                "format": "date-time",
                                                "description": "The first day, ISO 8601.",
                                                "example": "2026-10-01"
                                            },
                                            "end": {
                                                "type": "string",
                                                "format": "date-time",
                                                "description": "The last day, ISO 8601.",
                                                "example": "2026-10-31"
                                            }
                                        },
                                        "description": "Optional. The period the report covers. Defaults to the last month."
                                    }
                                },
                                "required": [
                                    "template_id",
                                    "format"
                                ]
                            },
                            "example": {
                                "template_id": "email-delivery",
                                "format": "pdf"
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/transport-rules": {
            "get": {
                "operationId": "getTransportRules",
                "summary": "List transport rules",
                "tags": [
                    "Transport rules"
                ],
                "x-required-scope": "transport_rules:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "transport_rule"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "The rule's ID, a ULID. Rule IDs are uppercase, such as `01M2RV5CEM4MT97RQ00ANRRFCP`; compare them exactly."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "The rule's name."
                                                            },
                                                            "description": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "Your note about the rule. Null when there is none."
                                                            },
                                                            "direction": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "enum": [
                                                                    "inbound",
                                                                    "outbound",
                                                                    "both"
                                                                ],
                                                                "description": "Which mail the rule checks: `inbound`, `outbound` or `both` (the default)."
                                                            },
                                                            "enabled": {
                                                                "type": "boolean",
                                                                "description": "A disabled rule keeps its priority and is not evaluated."
                                                            },
                                                            "priority": {
                                                                "type": "integer",
                                                                "nullable": true,
                                                                "description": "The order rules run in: lower runs first. The default is 100. `PUT /transport-rules/reorder` renumbers rules in steps of 10, so a rule can be put between two others."
                                                            },
                                                            "match": {
                                                                "type": "object",
                                                                "description": "How a message is matched: `logic` and its `conditions`.",
                                                                "properties": {
                                                                    "logic": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "all",
                                                                            "any"
                                                                        ],
                                                                        "description": "`all` means every condition must match (the default); `any` means one is enough."
                                                                    },
                                                                    "conditions": {
                                                                        "type": "array",
                                                                        "description": "The conditions, each with `field`, `operator` and `value`.",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "field": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "enum": [
                                                                                        "sender",
                                                                                        "recipient",
                                                                                        "subject",
                                                                                        "header",
                                                                                        "size",
                                                                                        "has_attachment"
                                                                                    ],
                                                                                    "description": "What is checked. `size` is the message size in bytes; `has_attachment` is true or false."
                                                                                },
                                                                                "operator": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "enum": [
                                                                                        "equals",
                                                                                        "contains",
                                                                                        "starts_with",
                                                                                        "ends_with",
                                                                                        "regex",
                                                                                        "greater_than",
                                                                                        "less_than"
                                                                                    ],
                                                                                    "description": "How `value` is compared with `field`."
                                                                                },
                                                                                "value": {
                                                                                    "type": "string",
                                                                                    "nullable": true,
                                                                                    "description": "What to compare with. Always a string, even for numbers: a size limit reads back as `\"1048576\"`. Parse it yourself for `greater_than` and `less_than`."
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "actions": {
                                                                "type": "array",
                                                                "description": "What happens to a matched message, in order.",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "type": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "enum": [
                                                                                "add_header",
                                                                                "modify_subject",
                                                                                "redirect",
                                                                                "bcc",
                                                                                "reject",
                                                                                "add_disclaimer",
                                                                                "quarantine"
                                                                            ],
                                                                            "description": "What is done to a message that matches."
                                                                        },
                                                                        "params": {
                                                                            "type": "object",
                                                                            "additionalProperties": true,
                                                                            "description": "The action's settings, keyed by name. Always an object, `{}` when there are none."
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true,
                                                                "description": "In ISO 8601 UTC."
                                                            },
                                                            "updated_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true,
                                                                "description": "In ISO 8601 UTC."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "operationId": "postTransportRules",
                "summary": "Create a transport rule",
                "tags": [
                    "Transport rules"
                ],
                "x-required-scope": "transport_rules:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transport_rule"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rule's ID, a ULID. Rule IDs are uppercase, such as `01M2RV5CEM4MT97RQ00ANRRFCP`; compare them exactly."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rule's name."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note about the rule. Null when there is none."
                                                        },
                                                        "direction": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "inbound",
                                                                "outbound",
                                                                "both"
                                                            ],
                                                            "description": "Which mail the rule checks: `inbound`, `outbound` or `both` (the default)."
                                                        },
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "A disabled rule keeps its priority and is not evaluated."
                                                        },
                                                        "priority": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "The order rules run in: lower runs first. The default is 100. `PUT /transport-rules/reorder` renumbers rules in steps of 10, so a rule can be put between two others."
                                                        },
                                                        "match": {
                                                            "type": "object",
                                                            "description": "How a message is matched: `logic` and its `conditions`.",
                                                            "properties": {
                                                                "logic": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "all",
                                                                        "any"
                                                                    ],
                                                                    "description": "`all` means every condition must match (the default); `any` means one is enough."
                                                                },
                                                                "conditions": {
                                                                    "type": "array",
                                                                    "description": "The conditions, each with `field`, `operator` and `value`.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "field": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "sender",
                                                                                    "recipient",
                                                                                    "subject",
                                                                                    "header",
                                                                                    "size",
                                                                                    "has_attachment"
                                                                                ],
                                                                                "description": "What is checked. `size` is the message size in bytes; `has_attachment` is true or false."
                                                                            },
                                                                            "operator": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "equals",
                                                                                    "contains",
                                                                                    "starts_with",
                                                                                    "ends_with",
                                                                                    "regex",
                                                                                    "greater_than",
                                                                                    "less_than"
                                                                                ],
                                                                                "description": "How `value` is compared with `field`."
                                                                            },
                                                                            "value": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "What to compare with. Always a string, even for numbers: a size limit reads back as `\"1048576\"`. Parse it yourself for `greater_than` and `less_than`."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "actions": {
                                                            "type": "array",
                                                            "description": "What happens to a matched message, in order.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "type": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "add_header",
                                                                            "modify_subject",
                                                                            "redirect",
                                                                            "bcc",
                                                                            "reject",
                                                                            "add_disclaimer",
                                                                            "quarantine"
                                                                        ],
                                                                        "description": "What is done to a message that matches."
                                                                    },
                                                                    "params": {
                                                                        "type": "object",
                                                                        "additionalProperties": true,
                                                                        "description": "The action's settings, keyed by name. Always an object, `{}` when there are none."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "In ISO 8601 UTC."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "In ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Flag mail from outside`.",
                                        "example": "Flag mail from outside",
                                        "x-example": "Spring newsletter"
                                    },
                                    "conditions": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "field": {
                                                    "type": "string",
                                                    "enum": [
                                                        "sender",
                                                        "recipient",
                                                        "subject",
                                                        "header",
                                                        "size",
                                                        "has_attachment"
                                                    ],
                                                    "description": "The part of the message to test. `size` is in bytes."
                                                },
                                                "operator": {
                                                    "type": "string",
                                                    "enum": [
                                                        "equals",
                                                        "contains",
                                                        "starts_with",
                                                        "ends_with",
                                                        "regex",
                                                        "greater_than",
                                                        "less_than"
                                                    ],
                                                    "description": "How to compare. `greater_than` and `less_than` are for `size`."
                                                },
                                                "value": {
                                                    "type": "string",
                                                    "description": "What to compare with."
                                                }
                                            },
                                            "required": [
                                                "field",
                                                "operator",
                                                "value"
                                            ]
                                        },
                                        "description": "What a message must match for the rule to run. At least one.",
                                        "example": [
                                            {
                                                "field": "sender",
                                                "operator": "ends_with",
                                                "value": "@example.com"
                                            }
                                        ]
                                    },
                                    "actions": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "type": {
                                                    "type": "string",
                                                    "enum": [
                                                        "add_header",
                                                        "modify_subject",
                                                        "redirect",
                                                        "bcc",
                                                        "reject",
                                                        "add_disclaimer",
                                                        "quarantine"
                                                    ],
                                                    "description": "What to do. `redirect` and `bcc` are accepted but not carried out yet. `add_disclaimer` adds a header, not text in the email."
                                                },
                                                "params": {
                                                    "type": "object",
                                                    "additionalProperties": true,
                                                    "description": "Settings for the action. `add_header`: `{\"name\": \"X-Flag\", \"value\": \"yes\"}`. `modify_subject`: `{\"prefix\": \"[External] \"}`. `reject`: `{\"message\": \"Not accepted\"}`. `add_disclaimer`: `{\"text\": \"\u2026\"}`."
                                                }
                                            },
                                            "required": [
                                                "type"
                                            ]
                                        },
                                        "description": "What to do to a matching message. At least one.",
                                        "example": [
                                            {
                                                "type": "modify_subject",
                                                "params": {
                                                    "prefix": "[External] "
                                                }
                                            }
                                        ]
                                    },
                                    "description": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 2000,
                                        "description": "Optional. A note for your team.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    },
                                    "direction": {
                                        "type": "string",
                                        "enum": [
                                            "inbound",
                                            "outbound",
                                            "both"
                                        ],
                                        "description": "Which mail the rule looks at: `inbound` (arriving), `outbound` (leaving) or `both`. Defaults to `both`.",
                                        "x-example": "inbound"
                                    },
                                    "condition_logic": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "any"
                                        ],
                                        "description": "How the conditions combine: `all` must match, or `any` one is enough. Defaults to `all`.",
                                        "x-example": "all"
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Lower numbers run first. Defaults to 100.",
                                        "x-example": 100
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "description": "Whether it is switched on.",
                                        "x-example": true
                                    }
                                },
                                "required": [
                                    "name",
                                    "conditions",
                                    "actions"
                                ]
                            },
                            "example": {
                                "name": "Flag mail from outside",
                                "conditions": [
                                    {
                                        "field": "sender",
                                        "operator": "ends_with",
                                        "value": "@example.com"
                                    }
                                ],
                                "actions": [
                                    {
                                        "type": "modify_subject",
                                        "params": {
                                            "prefix": "[External] "
                                        }
                                    }
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/transport-rules/{id}": {
            "get": {
                "operationId": "getTransportRulesId",
                "summary": "Retrieve a transport rule",
                "tags": [
                    "Transport rules"
                ],
                "x-required-scope": "transport_rules:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transport_rule"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rule's ID, a ULID. Rule IDs are uppercase, such as `01M2RV5CEM4MT97RQ00ANRRFCP`; compare them exactly."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rule's name."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note about the rule. Null when there is none."
                                                        },
                                                        "direction": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "inbound",
                                                                "outbound",
                                                                "both"
                                                            ],
                                                            "description": "Which mail the rule checks: `inbound`, `outbound` or `both` (the default)."
                                                        },
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "A disabled rule keeps its priority and is not evaluated."
                                                        },
                                                        "priority": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "The order rules run in: lower runs first. The default is 100. `PUT /transport-rules/reorder` renumbers rules in steps of 10, so a rule can be put between two others."
                                                        },
                                                        "match": {
                                                            "type": "object",
                                                            "description": "How a message is matched: `logic` and its `conditions`.",
                                                            "properties": {
                                                                "logic": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "all",
                                                                        "any"
                                                                    ],
                                                                    "description": "`all` means every condition must match (the default); `any` means one is enough."
                                                                },
                                                                "conditions": {
                                                                    "type": "array",
                                                                    "description": "The conditions, each with `field`, `operator` and `value`.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "field": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "sender",
                                                                                    "recipient",
                                                                                    "subject",
                                                                                    "header",
                                                                                    "size",
                                                                                    "has_attachment"
                                                                                ],
                                                                                "description": "What is checked. `size` is the message size in bytes; `has_attachment` is true or false."
                                                                            },
                                                                            "operator": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "equals",
                                                                                    "contains",
                                                                                    "starts_with",
                                                                                    "ends_with",
                                                                                    "regex",
                                                                                    "greater_than",
                                                                                    "less_than"
                                                                                ],
                                                                                "description": "How `value` is compared with `field`."
                                                                            },
                                                                            "value": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "What to compare with. Always a string, even for numbers: a size limit reads back as `\"1048576\"`. Parse it yourself for `greater_than` and `less_than`."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "actions": {
                                                            "type": "array",
                                                            "description": "What happens to a matched message, in order.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "type": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "add_header",
                                                                            "modify_subject",
                                                                            "redirect",
                                                                            "bcc",
                                                                            "reject",
                                                                            "add_disclaimer",
                                                                            "quarantine"
                                                                        ],
                                                                        "description": "What is done to a message that matches."
                                                                    },
                                                                    "params": {
                                                                        "type": "object",
                                                                        "additionalProperties": true,
                                                                        "description": "The action's settings, keyed by name. Always an object, `{}` when there are none."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "In ISO 8601 UTC."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "In ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "put": {
                "operationId": "putTransportRulesId",
                "summary": "Update a transport rule",
                "tags": [
                    "Transport rules"
                ],
                "x-required-scope": "transport_rules:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transport_rule"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rule's ID, a ULID. Rule IDs are uppercase, such as `01M2RV5CEM4MT97RQ00ANRRFCP`; compare them exactly."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rule's name."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note about the rule. Null when there is none."
                                                        },
                                                        "direction": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "inbound",
                                                                "outbound",
                                                                "both"
                                                            ],
                                                            "description": "Which mail the rule checks: `inbound`, `outbound` or `both` (the default)."
                                                        },
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "A disabled rule keeps its priority and is not evaluated."
                                                        },
                                                        "priority": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "The order rules run in: lower runs first. The default is 100. `PUT /transport-rules/reorder` renumbers rules in steps of 10, so a rule can be put between two others."
                                                        },
                                                        "match": {
                                                            "type": "object",
                                                            "description": "How a message is matched: `logic` and its `conditions`.",
                                                            "properties": {
                                                                "logic": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "all",
                                                                        "any"
                                                                    ],
                                                                    "description": "`all` means every condition must match (the default); `any` means one is enough."
                                                                },
                                                                "conditions": {
                                                                    "type": "array",
                                                                    "description": "The conditions, each with `field`, `operator` and `value`.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "field": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "sender",
                                                                                    "recipient",
                                                                                    "subject",
                                                                                    "header",
                                                                                    "size",
                                                                                    "has_attachment"
                                                                                ],
                                                                                "description": "What is checked. `size` is the message size in bytes; `has_attachment` is true or false."
                                                                            },
                                                                            "operator": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "equals",
                                                                                    "contains",
                                                                                    "starts_with",
                                                                                    "ends_with",
                                                                                    "regex",
                                                                                    "greater_than",
                                                                                    "less_than"
                                                                                ],
                                                                                "description": "How `value` is compared with `field`."
                                                                            },
                                                                            "value": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "What to compare with. Always a string, even for numbers: a size limit reads back as `\"1048576\"`. Parse it yourself for `greater_than` and `less_than`."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "actions": {
                                                            "type": "array",
                                                            "description": "What happens to a matched message, in order.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "type": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "add_header",
                                                                            "modify_subject",
                                                                            "redirect",
                                                                            "bcc",
                                                                            "reject",
                                                                            "add_disclaimer",
                                                                            "quarantine"
                                                                        ],
                                                                        "description": "What is done to a message that matches."
                                                                    },
                                                                    "params": {
                                                                        "type": "object",
                                                                        "additionalProperties": true,
                                                                        "description": "The action's settings, keyed by name. Always an object, `{}` when there are none."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "In ISO 8601 UTC."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "In ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "A name for your team, like `Flag mail from outside`.",
                                        "example": "Flag mail from outside",
                                        "x-example": "Spring newsletter"
                                    },
                                    "conditions": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "field": {
                                                    "type": "string",
                                                    "enum": [
                                                        "sender",
                                                        "recipient",
                                                        "subject",
                                                        "header",
                                                        "size",
                                                        "has_attachment"
                                                    ],
                                                    "description": "The part of the message to test. `size` is in bytes."
                                                },
                                                "operator": {
                                                    "type": "string",
                                                    "enum": [
                                                        "equals",
                                                        "contains",
                                                        "starts_with",
                                                        "ends_with",
                                                        "regex",
                                                        "greater_than",
                                                        "less_than"
                                                    ],
                                                    "description": "How to compare. `greater_than` and `less_than` are for `size`."
                                                },
                                                "value": {
                                                    "type": "string",
                                                    "description": "What to compare with."
                                                }
                                            },
                                            "required": [
                                                "field",
                                                "operator",
                                                "value"
                                            ]
                                        },
                                        "description": "What a message must match for the rule to run. At least one.",
                                        "example": [
                                            {
                                                "field": "sender",
                                                "operator": "ends_with",
                                                "value": "@example.com"
                                            }
                                        ]
                                    },
                                    "actions": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "type": {
                                                    "type": "string",
                                                    "enum": [
                                                        "add_header",
                                                        "modify_subject",
                                                        "redirect",
                                                        "bcc",
                                                        "reject",
                                                        "add_disclaimer",
                                                        "quarantine"
                                                    ],
                                                    "description": "What to do. `redirect` and `bcc` are accepted but not carried out yet. `add_disclaimer` adds a header, not text in the email."
                                                },
                                                "params": {
                                                    "type": "object",
                                                    "additionalProperties": true,
                                                    "description": "Settings for the action. `add_header`: `{\"name\": \"X-Flag\", \"value\": \"yes\"}`. `modify_subject`: `{\"prefix\": \"[External] \"}`. `reject`: `{\"message\": \"Not accepted\"}`. `add_disclaimer`: `{\"text\": \"\u2026\"}`."
                                                }
                                            },
                                            "required": [
                                                "type"
                                            ]
                                        },
                                        "description": "What to do to a matching message. At least one.",
                                        "example": [
                                            {
                                                "type": "modify_subject",
                                                "params": {
                                                    "prefix": "[External] "
                                                }
                                            }
                                        ]
                                    },
                                    "description": {
                                        "nullable": true,
                                        "type": "string",
                                        "maxLength": 2000,
                                        "description": "Optional. A note for your team.",
                                        "x-example": "Everyone who signed up at GITEX"
                                    },
                                    "direction": {
                                        "type": "string",
                                        "enum": [
                                            "inbound",
                                            "outbound",
                                            "both"
                                        ],
                                        "description": "Which mail the rule looks at: `inbound` (arriving), `outbound` (leaving) or `both`. Defaults to `both`.",
                                        "x-example": "inbound"
                                    },
                                    "condition_logic": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "any"
                                        ],
                                        "description": "How the conditions combine: `all` must match, or `any` one is enough. Defaults to `all`.",
                                        "x-example": "all"
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Lower numbers run first. Defaults to 100.",
                                        "x-example": 100
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "description": "Whether it is switched on.",
                                        "x-example": true
                                    }
                                },
                                "required": [
                                    "name",
                                    "conditions",
                                    "actions"
                                ]
                            },
                            "example": {
                                "name": "Flag mail from outside",
                                "conditions": [
                                    {
                                        "field": "sender",
                                        "operator": "ends_with",
                                        "value": "@example.com"
                                    }
                                ],
                                "actions": [
                                    {
                                        "type": "modify_subject",
                                        "params": {
                                            "prefix": "[External] "
                                        }
                                    }
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            },
            "delete": {
                "operationId": "deleteTransportRulesId",
                "summary": "Delete a transport rule",
                "tags": [
                    "Transport rules"
                ],
                "x-required-scope": "transport_rules:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. The rule is gone; a 200 is the whole answer."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/transport-rules/reorder": {
            "put": {
                "operationId": "putTransportRulesReorder",
                "summary": "Reorder (transport rule)",
                "tags": [
                    "Transport rules"
                ],
                "x-required-scope": "transport_rules:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "null",
                                                    "description": "No content. Re-read GET /transport-rules to see the new `priority` values, which are rewritten in steps of 10."
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "rule_ids": {
                                        "type": "array",
                                        "minItems": 1,
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "The IDs of all your rules, in the order they should run.",
                                        "x-example": [
                                            "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                        ]
                                    }
                                },
                                "required": [
                                    "rule_ids"
                                ]
                            },
                            "example": {
                                "rule_ids": [
                                    "01JBT8XQ2M9WYC3K4F6R7S8T9V"
                                ]
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/transport-rules/{id}/enable": {
            "put": {
                "operationId": "putTransportRulesIdEnable",
                "summary": "Enable a transport rule",
                "tags": [
                    "Transport rules"
                ],
                "x-required-scope": "transport_rules:write",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id identifier.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "transport_rule"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rule's ID, a ULID. Rule IDs are uppercase, such as `01M2RV5CEM4MT97RQ00ANRRFCP`; compare them exactly."
                                                        },
                                                        "name": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The rule's name."
                                                        },
                                                        "description": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your note about the rule. Null when there is none."
                                                        },
                                                        "direction": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "inbound",
                                                                "outbound",
                                                                "both"
                                                            ],
                                                            "description": "Which mail the rule checks: `inbound`, `outbound` or `both` (the default)."
                                                        },
                                                        "enabled": {
                                                            "type": "boolean",
                                                            "description": "A disabled rule keeps its priority and is not evaluated."
                                                        },
                                                        "priority": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "The order rules run in: lower runs first. The default is 100. `PUT /transport-rules/reorder` renumbers rules in steps of 10, so a rule can be put between two others."
                                                        },
                                                        "match": {
                                                            "type": "object",
                                                            "description": "How a message is matched: `logic` and its `conditions`.",
                                                            "properties": {
                                                                "logic": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        "all",
                                                                        "any"
                                                                    ],
                                                                    "description": "`all` means every condition must match (the default); `any` means one is enough."
                                                                },
                                                                "conditions": {
                                                                    "type": "array",
                                                                    "description": "The conditions, each with `field`, `operator` and `value`.",
                                                                    "items": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "field": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "sender",
                                                                                    "recipient",
                                                                                    "subject",
                                                                                    "header",
                                                                                    "size",
                                                                                    "has_attachment"
                                                                                ],
                                                                                "description": "What is checked. `size` is the message size in bytes; `has_attachment` is true or false."
                                                                            },
                                                                            "operator": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    "equals",
                                                                                    "contains",
                                                                                    "starts_with",
                                                                                    "ends_with",
                                                                                    "regex",
                                                                                    "greater_than",
                                                                                    "less_than"
                                                                                ],
                                                                                "description": "How `value` is compared with `field`."
                                                                            },
                                                                            "value": {
                                                                                "type": "string",
                                                                                "nullable": true,
                                                                                "description": "What to compare with. Always a string, even for numbers: a size limit reads back as `\"1048576\"`. Parse it yourself for `greater_than` and `less_than`."
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "actions": {
                                                            "type": "array",
                                                            "description": "What happens to a matched message, in order.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "type": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "enum": [
                                                                            "add_header",
                                                                            "modify_subject",
                                                                            "redirect",
                                                                            "bcc",
                                                                            "reject",
                                                                            "add_disclaimer",
                                                                            "quarantine"
                                                                        ],
                                                                        "description": "What is done to a message that matches."
                                                                    },
                                                                    "params": {
                                                                        "type": "object",
                                                                        "additionalProperties": true,
                                                                        "description": "The action's settings, keyed by name. Always an object, `{}` when there are none."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "In ISO 8601 UTC."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "In ISO 8601 UTC."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "enabled": {
                                        "type": "boolean",
                                        "description": "`true` turns the rule on, `false` off.",
                                        "x-example": true
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            },
                            "example": {
                                "enabled": true
                            }
                        }
                    }
                },
                "x-body-source": "form-request",
                "x-example-source": "generated"
            }
        },
        "/api/v1/api-keys": {
            "get": {
                "operationId": "getApiKeys",
                "summary": "List API keys",
                "tags": [
                    "Account"
                ],
                "x-required-scope": "account:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "object": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "api_key"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "description": "Unique identifier for the key."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "Your name for the key."
                                                            },
                                                            "prefix": {
                                                                "type": "string",
                                                                "description": "The start of the key, safe to log and show: `mk_live_` (or `mk_test_` for a test key) and 8 more characters. Use it to tell your keys apart. A key starting `mk_dead_` is an old key we revoked; see `revoked_reason`."
                                                            },
                                                            "scopes": {
                                                                "type": "array",
                                                                "items": {
                                                                    "$ref": "#/components/schemas/Scope"
                                                                },
                                                                "description": "What this key may do, as `resource:action` strings. An empty list allows nothing. Scopes cannot be changed later; make a new key instead."
                                                            },
                                                            "mode": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "live",
                                                                    "test"
                                                                ],
                                                                "description": "`test` (prefix `mk_test_`) for a test key: messages are built exactly as live ones would be, then stored in your Sandbox instead of being delivered. They are not in your live event log and use no credits. Use one in CI. The mode cannot be changed after the key is made."
                                                            },
                                                            "state": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "active",
                                                                    "expired",
                                                                    "revoked"
                                                                ],
                                                                "description": "Whether the key works. Only `active` does. A key past its expiry reads `expired`."
                                                            },
                                                            "revoked_reason": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "Why we revoked the key, when we did. Null when the key is not revoked, or you revoked it yourself."
                                                            },
                                                            "ip_allowlist": {
                                                                "type": "object",
                                                                "description": "Enforced at authentication time. `enabled: false` with a populated list is a configured allowlist that is currently off, not a contradiction.",
                                                                "properties": {
                                                                    "enabled": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "addresses": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "IPv4/IPv6 addresses or CIDR ranges."
                                                                    }
                                                                }
                                                            },
                                                            "last_used": {
                                                                "type": "object",
                                                                "description": "When and where the key was last used. This is updated at most once a minute, so it can be up to a minute behind.",
                                                                "properties": {
                                                                    "at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true,
                                                                        "description": "When the key was last used, in ISO 8601 UTC. Null means it has never been used."
                                                                    },
                                                                    "ip": {
                                                                        "type": "string",
                                                                        "nullable": true,
                                                                        "description": "The IP address the key was last used from. Use it to spot a leaked key used from somewhere you do not know. Null when the key was never used, or the address could not be read."
                                                                    }
                                                                }
                                                            },
                                                            "expires_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true,
                                                                "description": "When the key stops working, in ISO 8601 UTC. Null means it never expires. Read `state` to see whether the key works now."
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "description": "ISO 8601 UTC."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "The keys your organization holds, with their prefixes, scopes and last use.\n\nListing is available to a key; **creating and revoking are not.** A leaked key that\ncould mint its own replacement would outlive the revocation of the key that leaked,\nso those stay in the dashboard on purpose."
            }
        },
        "/api/v1/billing/usage": {
            "get": {
                "operationId": "getBillingUsage",
                "summary": "Get current usage",
                "tags": [
                    "Account"
                ],
                "x-required-scope": "account:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "usage"
                                                            ]
                                                        },
                                                        "mailboxes": {
                                                            "type": "object",
                                                            "properties": {
                                                                "free_used": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Free mailboxes in use."
                                                                },
                                                                "free_limit": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many free mailboxes you may have: five, or more if you had more before the pricing change. Buying seats does not change it. Null means no limit."
                                                                },
                                                                "seats": {
                                                                    "type": "object",
                                                                    "description": "Paid seats, per tier.",
                                                                    "properties": {
                                                                        "standard": {
                                                                            "type": "object",
                                                                            "description": "Seats of the Standard tier.",
                                                                            "properties": {
                                                                                "owned": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Seats bought at this tier. Null means unknown."
                                                                                },
                                                                                "assigned": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Seats in use. This can be more than `owned` after a downgrade. Null means unknown."
                                                                                }
                                                                            }
                                                                        },
                                                                        "pro": {
                                                                            "type": "object",
                                                                            "description": "Seats of the Pro tier.",
                                                                            "properties": {
                                                                                "owned": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Seats bought at this tier. Null means unknown."
                                                                                },
                                                                                "assigned": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Seats in use. This can be more than `owned` after a downgrade. Null means unknown."
                                                                                }
                                                                            }
                                                                        },
                                                                        "workplace": {
                                                                            "type": "object",
                                                                            "description": "Seats of the Workplace tier.",
                                                                            "properties": {
                                                                                "owned": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Seats bought at this tier. Null means unknown."
                                                                                },
                                                                                "assigned": {
                                                                                    "type": "integer",
                                                                                    "nullable": true,
                                                                                    "description": "Seats in use. This can be more than `owned` after a downgrade. Null means unknown."
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "send_credits": {
                                                            "type": "object",
                                                            "properties": {
                                                                "balance": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Send credits left, counted in emails, not money. Null means unknown."
                                                                },
                                                                "source": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "enforcer",
                                                                        "ledger"
                                                                    ],
                                                                    "description": "Where `balance` came from. `enforcer`: the live count on the mail server. `ledger`: our own copy, used when the mail server could not be reached; it can be up to 15 minutes behind."
                                                                },
                                                                "used_this_month": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Credits used this calendar month. Null means the mail server could not be reached; try again."
                                                                }
                                                            }
                                                        },
                                                        "app_send": {
                                                            "type": "object",
                                                            "description": "Email sent through the API and webmail, not through SMTP. If the mail server cannot be reached, every count here is null at once; try again rather than reading it as 0.",
                                                            "properties": {
                                                                "monthly": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "included": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails included each month. `0` when your plan has no monthly allowance."
                                                                        },
                                                                        "used": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails sent this month. Null means the mail server could not be reached."
                                                                        }
                                                                    }
                                                                },
                                                                "daily": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "included": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many emails you may send today. This is the limit actually in force, so it can differ from the free daily emails on the pricing page: those apply only to accounts with no credits and no Send plan, and `0` here is then correct. Null means the mail server could not be reached."
                                                                        },
                                                                        "used": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails sent today. Null means the mail server could not be reached."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "checks": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "Checks, where one check looks at one address to see whether its mailbox exists. They are used in this order: this month's plan checks, then bought checks, then older send credits. Every figure here counts checks. Null means they could not be read just now; try again.",
                                                            "properties": {
                                                                "plan_left": {
                                                                    "type": "integer",
                                                                    "description": "This month's plan checks still left. Months are UTC months. `0` when your plan includes none, or all are used."
                                                                },
                                                                "plan_limit": {
                                                                    "type": "integer",
                                                                    "description": "Checks your Marketing plan includes each UTC month. `0` when your plan includes none."
                                                                },
                                                                "bought": {
                                                                    "type": "integer",
                                                                    "description": "Checks you bought, or that we added for you. They never expire, and are used after this month's plan checks."
                                                                },
                                                                "credit_fallback": {
                                                                    "type": "integer",
                                                                    "description": "How many checks your send credits can still pay for, counted in checks. Only credits from before checks launched can pay, at 10 credits a check, and we always leave you at least 1 credit. Used last."
                                                                },
                                                                "forecast_days": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "About how many days your checks will last, at your rate over the last 7 days. Null when checks are not on yet, or you used none in the last 7 days."
                                                                },
                                                                "ran_out": {
                                                                    "type": "boolean",
                                                                    "description": "`true` when you have no checks left and a check could not be made for want of one this month (UTC). New contacts are then added and marked `not_checked`. Buying checks, or next month's plan checks, ends it."
                                                                },
                                                                "protection": {
                                                                    "type": "object",
                                                                    "description": "Your Bounce protection switch: whether each new contact is checked, using one check.",
                                                                    "properties": {
                                                                        "enabled": {
                                                                            "type": "boolean",
                                                                            "description": "Whether the switch is on for your account."
                                                                        },
                                                                        "is_default": {
                                                                            "type": "boolean",
                                                                            "description": "`true` while you have not chosen: it is then on when your Marketing plan includes checks, and off otherwise."
                                                                        }
                                                                    }
                                                                },
                                                                "upgrade": {
                                                                    "type": "object",
                                                                    "nullable": true,
                                                                    "description": "A bigger Marketing plan that would have cost you less this month (UTC): you spent more on check packs than the next plan costs, and it includes more checks every month. Null when there is no such plan.",
                                                                    "properties": {
                                                                        "spent_minor": {
                                                                            "type": "integer",
                                                                            "description": "What you spent on check packs this month, in the currency's minor unit (kobo, cents)."
                                                                        },
                                                                        "currency": {
                                                                            "type": "string",
                                                                            "description": "ISO 4217 code of both amounts."
                                                                        },
                                                                        "plan_key": {
                                                                            "type": "string",
                                                                            "description": "The suggested Marketing plan's product key."
                                                                        },
                                                                        "plan_checks": {
                                                                            "type": "integer",
                                                                            "description": "Checks that plan includes each month."
                                                                        },
                                                                        "price_difference_minor": {
                                                                            "type": "integer",
                                                                            "description": "What that plan costs a month on top of yours, in the minor unit."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "What your organization has sent this period, against its plan allowance and any purchased credits."
            }
        },
        "/api/v1/billing/entitlements": {
            "get": {
                "operationId": "getBillingEntitlements",
                "summary": "Entitlements (billing)",
                "tags": [
                    "Account"
                ],
                "x-required-scope": "account:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "entitlements"
                                                            ]
                                                        },
                                                        "plan": {
                                                            "type": "object",
                                                            "description": "What you have bought.",
                                                            "properties": {
                                                                "tier": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "free",
                                                                        "paid"
                                                                    ],
                                                                    "nullable": true,
                                                                    "description": "`free` or `paid`. Every account has one: an account that has bought nothing reads `free`."
                                                                },
                                                                "status": {
                                                                    "type": "string",
                                                                    "enum": [
                                                                        "pending",
                                                                        "active",
                                                                        "past_due",
                                                                        "suspended",
                                                                        "cancelled"
                                                                    ],
                                                                    "nullable": true,
                                                                    "description": "The subscription's status. Null means there is no subscription."
                                                                }
                                                            }
                                                        },
                                                        "seats": {
                                                            "type": "object",
                                                            "description": "Paid seats bought and in use, per tier. What a null on any leaf below means is stated ON THAT LEAF \u2014 this heading does not reach the field you are indexing into, and a caller reads the field it is using.",
                                                            "properties": {
                                                                "standard": {
                                                                    "type": "object",
                                                                    "description": "Seats of the standard tier. Both figures come from the entitlement snapshot, which counts them locally.",
                                                                    "properties": {
                                                                        "owned": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Seats bought at this tier. Null means unknown."
                                                                        },
                                                                        "assigned": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Seats in use. This can be more than `owned` after a downgrade. Null means unknown."
                                                                        }
                                                                    }
                                                                },
                                                                "pro": {
                                                                    "type": "object",
                                                                    "description": "Seats of the pro tier. Both figures come from the entitlement snapshot, which counts them locally.",
                                                                    "properties": {
                                                                        "owned": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Seats bought at this tier. Null means unknown."
                                                                        },
                                                                        "assigned": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Seats in use. This can be more than `owned` after a downgrade. Null means unknown."
                                                                        }
                                                                    }
                                                                },
                                                                "workplace": {
                                                                    "type": "object",
                                                                    "description": "Seats of the workplace tier. Both figures come from the entitlement snapshot, which counts them locally.",
                                                                    "properties": {
                                                                        "owned": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Seats bought at this tier. Null means unknown."
                                                                        },
                                                                        "assigned": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Seats in use. This can be more than `owned` after a downgrade. Null means unknown."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "mailbox_tiers": {
                                                            "type": "object",
                                                            "description": "What each mailbox tier gives one mailbox, the free tier included. For `daily_send_limit`, null means no limit; for `storage_bytes` and `assistant_actions`, null means unknown.",
                                                            "properties": {
                                                                "free": {
                                                                    "type": "object",
                                                                    "description": "What the free tier grants ONE mailbox.",
                                                                    "properties": {
                                                                        "storage_bytes": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Storage per mailbox, in bytes. Null means unknown."
                                                                        },
                                                                        "daily_send_limit": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails one mailbox of this tier may send per day. Null means no limit."
                                                                        },
                                                                        "assistant_actions": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Assistant actions per mailbox per month. `0` means none. Null means unknown."
                                                                        }
                                                                    }
                                                                },
                                                                "standard": {
                                                                    "type": "object",
                                                                    "description": "What the standard tier grants ONE mailbox.",
                                                                    "properties": {
                                                                        "storage_bytes": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Storage per mailbox, in bytes. Null means unknown."
                                                                        },
                                                                        "daily_send_limit": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails one mailbox of this tier may send per day. Null means no limit."
                                                                        },
                                                                        "assistant_actions": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Assistant actions per mailbox per month. `0` means none. Null means unknown."
                                                                        }
                                                                    }
                                                                },
                                                                "pro": {
                                                                    "type": "object",
                                                                    "description": "What the pro tier grants ONE mailbox.",
                                                                    "properties": {
                                                                        "storage_bytes": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Storage per mailbox, in bytes. Null means unknown."
                                                                        },
                                                                        "daily_send_limit": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails one mailbox of this tier may send per day. Null means no limit."
                                                                        },
                                                                        "assistant_actions": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Assistant actions per mailbox per month. `0` means none. Null means unknown."
                                                                        }
                                                                    }
                                                                },
                                                                "workplace": {
                                                                    "type": "object",
                                                                    "description": "What the workplace tier grants ONE mailbox.",
                                                                    "properties": {
                                                                        "storage_bytes": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Storage per mailbox, in bytes. Null means unknown."
                                                                        },
                                                                        "daily_send_limit": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails one mailbox of this tier may send per day. Null means no limit."
                                                                        },
                                                                        "assistant_actions": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Assistant actions per mailbox per month. `0` means none. Null means unknown."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "limits": {
                                                            "type": "object",
                                                            "description": "Limits for your whole account. Null means no limit.",
                                                            "properties": {
                                                                "max_mailboxes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Free mailboxes you may have: five, or more if you had more before the pricing change. Mailboxes on seats are limited by your seats instead. Null means no limit."
                                                                },
                                                                "max_domains": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Domains you may add. Null means no limit."
                                                                },
                                                                "max_aliases_per_mailbox": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Aliases each mailbox may have. Null means no limit."
                                                                },
                                                                "max_team_members": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "People you may invite to your account. Null means no limit."
                                                                }
                                                            }
                                                        },
                                                        "allowances": {
                                                            "type": "object",
                                                            "properties": {
                                                                "app_send_monthly": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Emails a month from your Send plan and seats. `0` when you have none. Null means unknown. For today's limit, see `GET /billing/usage`."
                                                                },
                                                                "send_credit_balance": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Your send credit balance, counted in emails, not money. To decide whether you can send right now, read `GET /billing/usage`, which shows the live figure. Null means unknown."
                                                                }
                                                            }
                                                        },
                                                        "features": {
                                                            "type": "object",
                                                            "description": "Feature entitlements. Whether a feature is GRANTED, not whether it is configured.",
                                                            "properties": {
                                                                "branded_webmail": {
                                                                    "type": "boolean"
                                                                },
                                                                "priority_support": {
                                                                    "type": "boolean"
                                                                },
                                                                "dedicated_ip": {
                                                                    "type": "boolean",
                                                                    "description": "Whether a dedicated IP may be requested. Its state is at `GET /dedicated-ip`."
                                                                }
                                                            }
                                                        },
                                                        "products": {
                                                            "type": "object",
                                                            "description": "Send (email from your apps) and Marketing (campaigns and journeys), each bought separately from mailboxes.",
                                                            "properties": {
                                                                "send": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "status": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "pending",
                                                                                "active",
                                                                                "past_due",
                                                                                "suspended",
                                                                                "cancelled"
                                                                            ],
                                                                            "nullable": true,
                                                                            "description": "The Send subscription's status. Null means there is no Send subscription."
                                                                        },
                                                                        "plan": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "The Send plan you have. Null means none, so the free plan applies."
                                                                        },
                                                                        "family": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "free",
                                                                                "pro",
                                                                                "scale"
                                                                            ],
                                                                            "nullable": true,
                                                                            "description": "Which Send plan sets the limits below: `free` when nothing is bought."
                                                                        },
                                                                        "included_monthly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails a month the Send plan includes; `0` on the free plan. Null means unknown."
                                                                        },
                                                                        "log_days": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "How many days of delivery logs you can see. Null means unknown."
                                                                        },
                                                                        "webhooks": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Webhooks you may add. Null means no limit."
                                                                        },
                                                                        "sandbox_inboxes": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Sandbox inboxes you may have. Null means unknown."
                                                                        },
                                                                        "sandbox_monthly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Emails a month your Sandbox accepts. Null means unknown."
                                                                        }
                                                                    }
                                                                },
                                                                "marketing": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "status": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "pending",
                                                                                "active",
                                                                                "past_due",
                                                                                "suspended",
                                                                                "cancelled"
                                                                            ],
                                                                            "nullable": true,
                                                                            "description": "The Marketing subscription's status. Null means there is no Marketing subscription."
                                                                        },
                                                                        "plan": {
                                                                            "type": "string",
                                                                            "nullable": true,
                                                                            "description": "The Marketing plan you have. Null means none; `family` says what applies."
                                                                        },
                                                                        "family": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "legacy",
                                                                                "free",
                                                                                "starter",
                                                                                "growth",
                                                                                "premium"
                                                                            ],
                                                                            "nullable": true,
                                                                            "description": "Which Marketing plan sets the limits below. `legacy` is an account made before Marketing plans existed, without one: no limits, and campaigns are paid from send credits."
                                                                        },
                                                                        "contacts": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Subscribed contacts the plan covers. Null means no limit."
                                                                        },
                                                                        "emails_monthly": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Marketing emails a month. Null means no limit (on `legacy`, each email is paid from credits)."
                                                                        },
                                                                        "segments": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Segments you may have. Null means no limit."
                                                                        },
                                                                        "journeys": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Journeys that may be live or paused at once. Null means no limit."
                                                                        },
                                                                        "journey_steps": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Steps one journey may have. Null means no limit."
                                                                        },
                                                                        "users": {
                                                                            "type": "integer",
                                                                            "nullable": true,
                                                                            "description": "Team members who may use Marketing. Null means no limit."
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "support_level": {
                                                            "type": "string",
                                                            "enum": [
                                                                "community",
                                                                "email",
                                                                "priority",
                                                                "named"
                                                            ],
                                                            "description": "The best support any product held includes."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/billing/subscription": {
            "get": {
                "operationId": "getBillingSubscription",
                "summary": "Subscription (billing)",
                "tags": [
                    "Account"
                ],
                "x-required-scope": "account:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "Your subscription, or null (with HTTP 200) when you have never subscribed.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "subscription"
                                                            ]
                                                        },
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Unique identifier for the subscription."
                                                        },
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "pending",
                                                                "active",
                                                                "past_due",
                                                                "suspended",
                                                                "cancelled"
                                                            ],
                                                            "description": "Where the subscription stands. `past_due` means a payment failed; `suspended` means sending has stopped."
                                                        },
                                                        "product_line": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mail",
                                                                "send",
                                                                "marketing"
                                                            ],
                                                            "description": "Which product this subscription is for. An organization holds at most one live subscription per line, each with its own interval, renewal and cancellation."
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "description": "ISO 4217 code, e.g. `NGN` or `USD`. THE CURRENCY THE CUSTOMER AGREED \u2014 nothing here is converted. Every amount below is in this currency's minor unit."
                                                        },
                                                        "interval": {
                                                            "type": "string",
                                                            "enum": [
                                                                "month",
                                                                "year"
                                                            ],
                                                            "description": "The billing period. (One-off prices exist for credit packs, which are bought outright and never appear on a subscription.)"
                                                        },
                                                        "items": {
                                                            "type": "array",
                                                            "description": "What the subscription is made of, one line per product, such as 3 Standard and 4 Pro seats.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "product_key": {
                                                                        "type": "string",
                                                                        "description": "The stable catalogue key, and the ONLY catalogue identifier published \u2014 it is the handle you pass to `POST /billing/subscription/items` to change quantity. Internal product and price row ids are not published."
                                                                    },
                                                                    "tier": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "standard",
                                                                            "pro",
                                                                            "workplace"
                                                                        ],
                                                                        "nullable": true,
                                                                        "description": "The mailbox tier this line buys seats of. Null when the line is not seats, such as a Send plan or an add-on; `product_key` names it."
                                                                    },
                                                                    "quantity": {
                                                                        "type": "integer",
                                                                        "description": "How many of this product."
                                                                    },
                                                                    "next_quantity": {
                                                                        "type": "integer",
                                                                        "nullable": true,
                                                                        "description": "A lower quantity that starts at the next renewal. Null when no change is planned. Until then the line keeps `quantity`; a reduction is not refunded."
                                                                    },
                                                                    "unit_amount": {
                                                                        "type": "integer",
                                                                        "description": "The price of one unit per `interval`, as a whole number in the smallest unit of `currency` (kobo for NGN, cents for USD): `150000` NGN is \u20a61,500.00. This is the price locked to this line."
                                                                    },
                                                                    "subtotal": {
                                                                        "type": "integer",
                                                                        "description": "`quantity` times `unit_amount`, in the smallest unit of `currency` (kobo for NGN, cents for USD)."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "The total for one `interval`, in the smallest unit of `currency` (kobo for NGN, cents for USD): `150000` NGN is \u20a61,500.00. Tax and payment fees are not included."
                                                        },
                                                        "current_period_start": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the current billing period began. Null until the first payment succeeds (`status` is then `pending`)."
                                                        },
                                                        "current_period_end": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the current period ends. With `auto_renew` on, `total` is charged again then. Null until the first payment succeeds."
                                                        },
                                                        "auto_renew": {
                                                            "type": "boolean"
                                                        },
                                                        "cancelled_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When cancellation was asked for. Null when it was not. Service continues until `current_period_end`."
                                                        },
                                                        "cancel_at_period_end": {
                                                            "type": "boolean",
                                                            "description": "True when the customer cancelled and the subscription is still running to `current_period_end`. It can be undone with `POST /billing/subscriptions/{line}/resume` until then."
                                                        },
                                                        "next_billing_date": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When you will next be charged. Null when no charge is coming: it is cancelling, waiting for its first payment, or has ended."
                                                        },
                                                        "price_locked_until": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "Prices on this subscription will not rise before this date. Null when there is no price lock: monthly plans have none, paying a year ahead does."
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the subscription was created at checkout. Billing starts at `current_period_start`."
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the subscription last changed."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/billing/send-plan": {
            "get": {
                "operationId": "getBillingSendPlan",
                "summary": "Send Plan (billing)",
                "tags": [
                    "Account"
                ],
                "x-required-scope": "account:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "description": "The Send plan held, this month's overage, and the spend cap. No payment processor is named: which rail would collect an overage charge is our arrangement, not the customer's data.",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "send_plan"
                                                            ]
                                                        },
                                                        "plan_key": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The Send plan you have. Null when you have none."
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The currency every amount here uses, as an ISO 4217 code such as `NGN` or `USD`. Amounts are in its smallest unit. `NGN` when you have no plan."
                                                        },
                                                        "included_monthly": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Emails a month the plan includes. `0` when you have no plan."
                                                        },
                                                        "used_this_month": {
                                                            "type": "integer",
                                                            "nullable": true,
                                                            "description": "Emails sent this calendar month. Null means the mail server could not be reached; try again rather than reading it as 0. `overage.emails`, `overage.amount` and `spend_cap.reached` are then null too."
                                                        },
                                                        "overage": {
                                                            "type": "object",
                                                            "description": "Sending past `included_monthly`, and what it costs.",
                                                            "properties": {
                                                                "emails": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Emails past what your plan includes. Null when `used_this_month` is null."
                                                                },
                                                                "amount": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "What the extra emails cost so far this month, in the smallest unit of `currency` (kobo for NGN, cents for USD): `150000` NGN is \u20a61,500.00. Null when `used_this_month` is null; it is not a zero bill."
                                                                },
                                                                "rate_per_thousand": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The price per 1,000 emails past what your plan includes, in the smallest unit of `currency` (kobo for NGN, cents for USD). Null when the plan has no overage price."
                                                                }
                                                            }
                                                        },
                                                        "spend_cap": {
                                                            "type": "object",
                                                            "description": "An optional ceiling on overage spend for the month.",
                                                            "properties": {
                                                                "amount": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Your spending cap, in the smallest unit of `currency` (kobo for NGN, cents for USD). Null means no cap. `0` is different: it means never charge me for extra emails. To remove the cap, send null, not 0."
                                                                },
                                                                "reached": {
                                                                    "type": "boolean",
                                                                    "nullable": true,
                                                                    "description": "Whether you have reached the cap. Null when there is a cap but this month's sending could not be read. False when there is no cap."
                                                                },
                                                                "ceiling_emails": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Your cap as a number of emails, which is how the mail server enforces it. Null when there is no cap."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/v1/dedicated-ip": {
            "get": {
                "operationId": "getDedicatedIp",
                "summary": "Get dedicated IP status",
                "tags": [
                    "Account"
                ],
                "x-required-scope": "account:read",
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "SessionToken": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "object": {
                                                            "type": "string",
                                                            "enum": [
                                                                "dedicated_ip"
                                                            ]
                                                        },
                                                        "state": {
                                                            "type": "string",
                                                            "enum": [
                                                                "shared",
                                                                "requested",
                                                                "provisioning",
                                                                "warming",
                                                                "live",
                                                                "paused",
                                                                "quarantined"
                                                            ],
                                                            "nullable": true,
                                                            "description": "Where your dedicated IP stands.\n\n- `shared`: you use the shared pool (the default).\n- `requested`: you applied and it is being reviewed.\n- `provisioning`: approved and being set up.\n- `warming`: assigned and ramping up; see `warmup`.\n- `live`: fully warmed and sending at full rate.\n- `paused`: sending stopped, the address kept.\n- `quarantined`: withdrawn because of a reputation problem."
                                                        },
                                                        "address": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "Your dedicated IP address. Null until one is assigned."
                                                        },
                                                        "spf_include": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "What to add to your SPF record to allow this address, such as `include:spf.your-slug.example`. Null until an address is assigned."
                                                        },
                                                        "requested_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When you applied for a dedicated IP. Null if you never have."
                                                        },
                                                        "live_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true,
                                                            "description": "When the address finished warming and began sending at full rate. Null until then; `state` says where it is."
                                                        },
                                                        "warmup": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "description": "The warm-up, while it runs. Null when there is none. If `state` is `warming` and this is null, the figures could not be read: try again.",
                                                            "properties": {
                                                                "day": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The day of the warm-up schedule."
                                                                },
                                                                "daily_limit": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many recipients this address may take today."
                                                                },
                                                                "sent_today": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Recipients this address has taken today."
                                                                },
                                                                "remaining": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "How many more recipients it may take today: `daily_limit` minus `sent_today`, never below 0."
                                                                },
                                                                "completes_on": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When the warm-up is due to finish. Null when it cannot be worked out."
                                                                }
                                                            }
                                                        },
                                                        "terms": {
                                                            "type": "object",
                                                            "description": "The dedicated-IP addendum, as it stands for this organization.",
                                                            "properties": {
                                                                "version_in_force": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The version of the dedicated IP terms a new application must accept."
                                                                },
                                                                "accepted_version": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "description": "The version of the terms you accepted. Null when you have not accepted any. It can be older than `version_in_force`; that is normal."
                                                                },
                                                                "accepted_at": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When you accepted the terms. Null when you have not."
                                                                }
                                                            }
                                                        },
                                                        "eligibility": {
                                                            "type": "object",
                                                            "description": "Whether a dedicated IP can be requested, and the figures worth seeing before deciding to.",
                                                            "properties": {
                                                                "can_request": {
                                                                    "type": "boolean",
                                                                    "description": "Whether a request would be accepted right now. Governed by `requirements` alone; everything else in this object is disclosure and never blocks a request."
                                                                },
                                                                "requirements": {
                                                                    "type": "object",
                                                                    "description": "The two HARD requirements. Both must be true for `can_request`.",
                                                                    "properties": {
                                                                        "domain_verified": {
                                                                            "type": "boolean",
                                                                            "description": "At least one domain verified for sending. See `verified_domains` for which."
                                                                        },
                                                                        "marketing_approved": {
                                                                            "type": "boolean"
                                                                        }
                                                                    }
                                                                },
                                                                "verified_domains": {
                                                                    "type": "array",
                                                                    "items": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": "Domain NAMES, not ids \u2014 the list that satisfies `domain_verified`, readable without a second lookup."
                                                                },
                                                                "monthly_volume": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Emails you sent in the last 30 days."
                                                                },
                                                                "volume_threshold": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "The monthly volume at which a dedicated IP starts to pay off. Compare it with `monthly_volume`."
                                                                },
                                                                "bounce_rate": {
                                                                    "type": "number",
                                                                    "format": "float",
                                                                    "nullable": true,
                                                                    "description": "The percentage of the last 30 days' deliveries that bounced. Null when nothing was sent."
                                                                }
                                                            }
                                                        },
                                                        "can_return_to_shared": {
                                                            "type": "boolean",
                                                            "description": "Whether this organization may move back to the shared pool, which the addendum permits at any time. It is also how an application is withdrawn."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                },
                "description": "Your dedicated sending address and its warm-up state. An organization on a shared IP gets a populated object whose `state` is `shared` and whose `address` is null \u2014 NOT a null result, and never an error. Reachable with an organization API key carrying `account:read`; a key without that scope is refused with 403."
            }
        },
        "/api/v1/mailbox-auth/login": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Get a mailbox token",
                "description": "Exchanges a mailbox's own email address and password for a **token**. Send it as `Authorization: Bearer <token>` on every other Mailbox API call.\n\n**Two-factor.** If the mailbox has two-factor sign-in on, the first call answers `two_factor_required: true` and no token. Call again with the same email and password plus `two_factor_code` (or a recovery code).\n\n**How long it lasts.** A browser session lasts 8 hours idle and 7 days at most. An app that sends `X-Client-Platform` gets 30 days idle and 180 days at most. `expires_at` and `idle_timeout_seconds` say exactly.\n\n**Temporary password.** If an admin reset the password, you still get a token, with `must_change_password: true`. Until `POST /security/password` succeeds, every other call is refused, except logout.\n\nThe password is checked by the mail server itself, so it is always the same password a mail app uses.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | Wrong email or password, or a wrong two-factor code. The message is the same for both, on purpose: `Invalid email or password`. |\n| `422` | `email_address` or `password` is missing or too long. |\n| `429` | Too many failed attempts from this IP or for this address: `Too many failed attempts. Try again later.` |",
                "operationId": "login_api_v1_mailbox_auth_login_post",
                "parameters": [
                    {
                        "name": "X-Client-Platform",
                        "in": "header",
                        "required": false,
                        "description": "Your app's platform, for the longer app sessions: `ios`, `android`, `macos`, `windows` or `linux`. Leave it out from a browser.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "ios"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "email_address": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "title": "Email Address",
                                        "description": "The mailbox's full address."
                                    },
                                    "password": {
                                        "type": "string",
                                        "maxLength": 1024,
                                        "title": "Password",
                                        "description": "The mailbox password: the same one a mail app uses."
                                    },
                                    "two_factor_code": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 32
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Two Factor Code",
                                        "description": "Only when the first call answered `two_factor_required`: the 6-digit code from the authenticator app, or a recovery code."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "email_address",
                                    "password"
                                ],
                                "title": "MailboxLoginRequest"
                            },
                            "example": {
                                "email_address": "ada@yourdomain.com",
                                "password": "her-mailbox-password"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Signed in, or (with two-factor on and no code sent) a request for the code.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "token": {
                                                            "type": "string",
                                                            "description": "Send as `Authorization: Bearer <token>`."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "description": "When the session ends at the latest (ISO 8601 with offset)."
                                                        },
                                                        "idle_timeout_seconds": {
                                                            "type": "integer",
                                                            "description": "The session ends after this long without a call."
                                                        },
                                                        "email_address": {
                                                            "type": "string"
                                                        },
                                                        "email_account": {
                                                            "type": "object",
                                                            "properties": {
                                                                "id": {
                                                                    "type": "string"
                                                                },
                                                                "email_address": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": [
                                                                        "string",
                                                                        "null"
                                                                    ]
                                                                }
                                                            }
                                                        },
                                                        "must_change_password": {
                                                            "type": "boolean",
                                                            "description": "True: change the password first (`POST /security/password`)."
                                                        },
                                                        "password_change_reason": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "client_platform": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The platform the server read from `X-Client-Platform`. Null means a web browser."
                                                        },
                                                        "csrf_token": {
                                                            "type": "string",
                                                            "description": "Only for browsers using the session cookie instead of the token."
                                                        },
                                                        "two_factor_required": {
                                                            "type": "boolean",
                                                            "description": "Only on the two-factor prompt: no token yet, send `two_factor_code`."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Signed in",
                                    "data": {
                                        "token": "mbx_3q9Xk2Lr7...redacted",
                                        "expires_at": "2026-04-09T10:00:00+00:00",
                                        "idle_timeout_seconds": 2592000,
                                        "email_address": "ada@yourdomain.com",
                                        "email_account": {
                                            "id": "01J9ZK3M5Q8R2T4V6W8X0Y2Z4A",
                                            "email_address": "ada@yourdomain.com",
                                            "name": "Ada Obi"
                                        },
                                        "must_change_password": false,
                                        "password_change_reason": null,
                                        "client_platform": "ios",
                                        "csrf_token": "J3k...redacted"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`email_address` or `password` is missing or too long.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Wrong email or password, or a wrong two-factor code. The message is the same for both, on purpose: `Invalid email or password`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many failed attempts from this IP or for this address: `Too many failed attempts. Try again later.`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": []
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox-auth/logout": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Sign out (revoke the token)",
                "description": "Ends the session: the token stops working at once. Calling it again is harmless. Send the token you want to revoke.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |",
                "operationId": "logout_api_v1_mailbox_auth_logout_post",
                "responses": {
                    "200": {
                        "description": "Signed out.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Signed out"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Authorization",
                        "in": "header",
                        "required": true,
                        "description": "`Bearer <token>` \u2014 the session to end.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Bearer mbx_3q9Xk2Lr7..."
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/capabilities": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "What this mailbox can do",
                "description": "Which features this mail server offers this mailbox, and the shared mailboxes it may use. Call it once after signing in and hide what is off.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "capabilities_api_v1_mailbox_capabilities_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "email_address": {
                                                            "type": "string"
                                                        },
                                                        "capabilities": {
                                                            "type": "object",
                                                            "properties": {
                                                                "mail": {
                                                                    "type": "boolean"
                                                                },
                                                                "send": {
                                                                    "type": "boolean"
                                                                },
                                                                "settings": {
                                                                    "type": "boolean"
                                                                },
                                                                "two_factor": {
                                                                    "type": "boolean"
                                                                },
                                                                "rules": {
                                                                    "type": "boolean"
                                                                },
                                                                "forwarding": {
                                                                    "type": "boolean"
                                                                },
                                                                "vacation": {
                                                                    "type": "boolean"
                                                                },
                                                                "ai": {
                                                                    "type": "boolean"
                                                                },
                                                                "calendar": {
                                                                    "type": "boolean"
                                                                },
                                                                "contacts": {
                                                                    "type": "boolean"
                                                                },
                                                                "scheduled_send": {
                                                                    "type": "boolean"
                                                                },
                                                                "bulk_actions": {
                                                                    "type": "boolean"
                                                                }
                                                            }
                                                        },
                                                        "shared_mailboxes": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "address": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "permission": {
                                                                        "type": "string",
                                                                        "description": "read, send or full."
                                                                    },
                                                                    "can_send": {
                                                                        "type": "boolean"
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Capabilities",
                                    "data": {
                                        "email_address": "ada@yourdomain.com",
                                        "capabilities": {
                                            "mail": true,
                                            "send": true,
                                            "settings": true,
                                            "two_factor": true,
                                            "rules": true,
                                            "forwarding": true,
                                            "vacation": true,
                                            "ai": false,
                                            "calendar": true,
                                            "contacts": true,
                                            "scheduled_send": true,
                                            "bulk_actions": true
                                        },
                                        "shared_mailboxes": [
                                            {
                                                "address": "finance@yourdomain.com",
                                                "name": "Finance",
                                                "permission": "send",
                                                "can_send": true
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/folders": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List folders",
                "description": "Every folder in the mailbox, with message and unread counts. `role` marks the special ones (inbox, sent, drafts, trash, junk, archive); use `name` wherever another call takes a `folder`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "folders_api_v1_mailbox_folders_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string",
                                                                "description": "A stable id for the folder (a hash of its name)."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "The folder's full name; use it as `folder` in other calls."
                                                            },
                                                            "role": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "enum": [
                                                                    "inbox",
                                                                    "sent",
                                                                    "drafts",
                                                                    "trash",
                                                                    "junk",
                                                                    "archive",
                                                                    "scheduled",
                                                                    null
                                                                ]
                                                            },
                                                            "total": {
                                                                "type": "integer",
                                                                "description": "Messages in the folder."
                                                            },
                                                            "unread": {
                                                                "type": "integer"
                                                            },
                                                            "uid_next": {
                                                                "type": "integer"
                                                            },
                                                            "uid_validity": {
                                                                "type": "integer"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Folders retrieved successfully",
                                    "data": [
                                        {
                                            "id": "7e33429f656f1e6e9d79b29c3f82c57e",
                                            "name": "INBOX",
                                            "role": "inbox",
                                            "total": 1284,
                                            "unread": 3,
                                            "uid_next": 4822,
                                            "uid_validity": 1712345678
                                        },
                                        {
                                            "id": "ad0b7f0a1fb9a8b5bc8cd2e4c4c6f1a2",
                                            "name": "Sent",
                                            "role": "sent",
                                            "total": 412,
                                            "unread": 0,
                                            "uid_next": 413,
                                            "uid_validity": 1712345679
                                        },
                                        {
                                            "id": "3b9c3ed2a7b3d0c4f1e0a4d9b8f7e6c5",
                                            "name": "Drafts",
                                            "role": "drafts",
                                            "total": 2,
                                            "unread": 0,
                                            "uid_next": 31,
                                            "uid_validity": 1712345680
                                        },
                                        {
                                            "id": "9c1f3a0e2b4d5c6e7f8a9b0c1d2e3f40",
                                            "name": "Clients",
                                            "role": null,
                                            "total": 87,
                                            "unread": 0,
                                            "uid_next": 88,
                                            "uid_validity": 1712345690
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Create a folder",
                "description": "Creates a folder and answers with the full folder list.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | The mail server refused the name, for example because a folder by that name exists. |\n| `422` | The name is empty, longer than 255 characters, or contains `/`, `\\` or control characters. |",
                "operationId": "create_folder_route_api_v1_mailbox_folders_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "minLength": 1,
                                        "pattern": "^[^/\\\\\\x00-\\x1F]+$",
                                        "title": "Name",
                                        "description": "The new folder's name, up to 255 characters. Not `/`, `\\` or control characters."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "title": "CreateFolderRequest"
                            },
                            "example": {
                                "name": "Clients"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string",
                                                                "description": "A stable id for the folder (a hash of its name)."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "The folder's full name; use it as `folder` in other calls."
                                                            },
                                                            "role": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "enum": [
                                                                    "inbox",
                                                                    "sent",
                                                                    "drafts",
                                                                    "trash",
                                                                    "junk",
                                                                    "archive",
                                                                    "scheduled",
                                                                    null
                                                                ]
                                                            },
                                                            "total": {
                                                                "type": "integer",
                                                                "description": "Messages in the folder."
                                                            },
                                                            "unread": {
                                                                "type": "integer"
                                                            },
                                                            "uid_next": {
                                                                "type": "integer"
                                                            },
                                                            "uid_validity": {
                                                                "type": "integer"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Folder created successfully",
                                    "data": [
                                        {
                                            "id": "7e33429f656f1e6e9d79b29c3f82c57e",
                                            "name": "INBOX",
                                            "role": "inbox",
                                            "total": 1284,
                                            "unread": 3,
                                            "uid_next": 4822,
                                            "uid_validity": 1712345678
                                        },
                                        {
                                            "id": "ad0b7f0a1fb9a8b5bc8cd2e4c4c6f1a2",
                                            "name": "Sent",
                                            "role": "sent",
                                            "total": 412,
                                            "unread": 0,
                                            "uid_next": 413,
                                            "uid_validity": 1712345679
                                        },
                                        {
                                            "id": "3b9c3ed2a7b3d0c4f1e0a4d9b8f7e6c5",
                                            "name": "Drafts",
                                            "role": "drafts",
                                            "total": 2,
                                            "unread": 0,
                                            "uid_next": 31,
                                            "uid_validity": 1712345680
                                        },
                                        {
                                            "id": "9c1f3a0e2b4d5c6e7f8a9b0c1d2e3f40",
                                            "name": "Clients",
                                            "role": null,
                                            "total": 87,
                                            "unread": 0,
                                            "uid_next": 88,
                                            "uid_validity": 1712345690
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The name is empty, longer than 255 characters, or contains `/`, `\\` or control characters.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The mail server refused the name, for example because a folder by that name exists.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/folders/{folder}": {
            "patch": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Rename a folder",
                "description": "`{folder}` is the folder's `id` from `GET /folders`. Inbox and the special folders (Sent, Drafts, Junk, Trash, Archive) cannot be renamed.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | The mail server refused the new name (for example, it is taken). |\n| `409` | A special folder: `error_code: cannot_rename_special_folder`. |",
                "operationId": "rename_folder_route_api_v1_mailbox_folders__folder__patch",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Folder"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "minLength": 1,
                                        "pattern": "^[^/\\\\\\x00-\\x1F]+$",
                                        "title": "Name",
                                        "description": "The new name."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "title": "RenameFolderRequest"
                            },
                            "example": {
                                "name": "Clients (2026)"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "folders": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "A stable id for the folder (a hash of its name)."
                                                                    },
                                                                    "name": {
                                                                        "type": "string",
                                                                        "description": "The folder's full name; use it as `folder` in other calls."
                                                                    },
                                                                    "role": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "enum": [
                                                                            "inbox",
                                                                            "sent",
                                                                            "drafts",
                                                                            "trash",
                                                                            "junk",
                                                                            "archive",
                                                                            "scheduled",
                                                                            null
                                                                        ]
                                                                    },
                                                                    "total": {
                                                                        "type": "integer",
                                                                        "description": "Messages in the folder."
                                                                    },
                                                                    "unread": {
                                                                        "type": "integer"
                                                                    },
                                                                    "uid_next": {
                                                                        "type": "integer"
                                                                    },
                                                                    "uid_validity": {
                                                                        "type": "integer"
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Folder renamed",
                                    "data": {
                                        "id": "1f2e3d4c5b6a79880716253443526170",
                                        "name": "Clients (2026)",
                                        "folders": [
                                            {
                                                "id": "7e33429f656f1e6e9d79b29c3f82c57e",
                                                "name": "INBOX",
                                                "role": "inbox",
                                                "total": 1284,
                                                "unread": 3,
                                                "uid_next": 4822,
                                                "uid_validity": 1712345678
                                            },
                                            {
                                                "id": "ad0b7f0a1fb9a8b5bc8cd2e4c4c6f1a2",
                                                "name": "Sent",
                                                "role": "sent",
                                                "total": 412,
                                                "unread": 0,
                                                "uid_next": 413,
                                                "uid_validity": 1712345679
                                            },
                                            {
                                                "id": "3b9c3ed2a7b3d0c4f1e0a4d9b8f7e6c5",
                                                "name": "Drafts",
                                                "role": "drafts",
                                                "total": 2,
                                                "unread": 0,
                                                "uid_next": 31,
                                                "uid_validity": 1712345680
                                            },
                                            {
                                                "id": "9c1f3a0e2b4d5c6e7f8a9b0c1d2e3f40",
                                                "name": "Clients",
                                                "role": null,
                                                "total": 87,
                                                "unread": 0,
                                                "uid_next": 88,
                                                "uid_validity": 1712345690
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The mail server refused the new name (for example, it is taken).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "A special folder: `error_code: cannot_rename_special_folder`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Delete an empty folder",
                "description": "`{folder}` is the folder's `id` from `GET /folders`. Empty it first: move or delete its messages and subfolders. Answers with the folder list that is left.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `409` | `error_code` says why: `cannot_delete_special_folder`, `folder_not_empty` or `folder_has_subfolders`. |",
                "operationId": "delete_folder_route_api_v1_mailbox_folders__folder__delete",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Folder"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string",
                                                                "description": "A stable id for the folder (a hash of its name)."
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "description": "The folder's full name; use it as `folder` in other calls."
                                                            },
                                                            "role": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "enum": [
                                                                    "inbox",
                                                                    "sent",
                                                                    "drafts",
                                                                    "trash",
                                                                    "junk",
                                                                    "archive",
                                                                    "scheduled",
                                                                    null
                                                                ]
                                                            },
                                                            "total": {
                                                                "type": "integer",
                                                                "description": "Messages in the folder."
                                                            },
                                                            "unread": {
                                                                "type": "integer"
                                                            },
                                                            "uid_next": {
                                                                "type": "integer"
                                                            },
                                                            "uid_validity": {
                                                                "type": "integer"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Folder deleted",
                                    "data": [
                                        {
                                            "id": "7e33429f656f1e6e9d79b29c3f82c57e",
                                            "name": "INBOX",
                                            "role": "inbox",
                                            "total": 1284,
                                            "unread": 3,
                                            "uid_next": 4822,
                                            "uid_validity": 1712345678
                                        },
                                        {
                                            "id": "ad0b7f0a1fb9a8b5bc8cd2e4c4c6f1a2",
                                            "name": "Sent",
                                            "role": "sent",
                                            "total": 412,
                                            "unread": 0,
                                            "uid_next": 413,
                                            "uid_validity": 1712345679
                                        },
                                        {
                                            "id": "3b9c3ed2a7b3d0c4f1e0a4d9b8f7e6c5",
                                            "name": "Drafts",
                                            "role": "drafts",
                                            "total": 2,
                                            "unread": 0,
                                            "uid_next": 31,
                                            "uid_validity": 1712345680
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "`error_code` says why: `cannot_delete_special_folder`, `folder_not_empty` or `folder_has_subfolders`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List messages",
                "description": "Messages in one folder, newest first, a page at a time. `folder` defaults to the inbox. `search` (or `q`) matches the sender, recipients, subject and body. Combine the filters freely. Page with `offset` and `limit` (default 50, at most 200) while `has_more` is true.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | No folder by that name. |",
                "operationId": "messages_api_v1_mailbox_messages_get",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "maxLength": 255
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Folder"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "maxLength": 255
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Search"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "maxLength": 255
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Q"
                        }
                    },
                    {
                        "name": "unread",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false,
                            "title": "Unread"
                        }
                    },
                    {
                        "name": "starred",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false,
                            "title": "Starred"
                        }
                    },
                    {
                        "name": "label",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "maxLength": 40
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Label"
                        }
                    },
                    {
                        "name": "attachments",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false,
                            "title": "Attachments"
                        }
                    },
                    {
                        "name": "mentioned",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false,
                            "title": "Mentioned"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 200,
                            "minimum": 1,
                            "default": 50,
                            "title": "Limit"
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0,
                            "title": "Offset"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "messages": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "description": "This message's id: `folder:uid`, e.g. `INBOX:4821`. Use it in every per-message call."
                                                                    },
                                                                    "folder": {
                                                                        "type": "string"
                                                                    },
                                                                    "subject": {
                                                                        "type": "string"
                                                                    },
                                                                    "from": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "name": {
                                                                                    "type": [
                                                                                        "string",
                                                                                        "null"
                                                                                    ]
                                                                                },
                                                                                "email": {
                                                                                    "type": "string"
                                                                                }
                                                                            },
                                                                            "required": [
                                                                                "email"
                                                                            ]
                                                                        }
                                                                    },
                                                                    "to": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "name": {
                                                                                    "type": [
                                                                                        "string",
                                                                                        "null"
                                                                                    ]
                                                                                },
                                                                                "email": {
                                                                                    "type": "string"
                                                                                }
                                                                            },
                                                                            "required": [
                                                                                "email"
                                                                            ]
                                                                        }
                                                                    },
                                                                    "cc": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "name": {
                                                                                    "type": [
                                                                                        "string",
                                                                                        "null"
                                                                                    ]
                                                                                },
                                                                                "email": {
                                                                                    "type": "string"
                                                                                }
                                                                            },
                                                                            "required": [
                                                                                "email"
                                                                            ]
                                                                        }
                                                                    },
                                                                    "received_at": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "description": "ISO 8601 with offset."
                                                                    },
                                                                    "size": {
                                                                        "type": "integer",
                                                                        "description": "Bytes."
                                                                    },
                                                                    "has_attachment": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "is_read": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "is_starred": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "is_answered": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "is_draft": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "keywords": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "description": "Labels on this message."
                                                                    },
                                                                    "preview": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "description": "The first line or two of text."
                                                                    },
                                                                    "thread_id": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "message_id": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "description": "The RFC 5322 Message-ID header."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "total": {
                                                            "type": "integer",
                                                            "description": "Matching messages in all pages."
                                                        },
                                                        "offset": {
                                                            "type": "integer"
                                                        },
                                                        "limit": {
                                                            "type": "integer"
                                                        },
                                                        "has_more": {
                                                            "type": "boolean"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Messages retrieved successfully",
                                    "data": {
                                        "messages": [
                                            {
                                                "id": "INBOX:4821",
                                                "folder": "INBOX",
                                                "subject": "Re: the quarterly numbers",
                                                "from": [
                                                    {
                                                        "name": "Tunde Bello",
                                                        "email": "tunde@example.com"
                                                    }
                                                ],
                                                "to": [
                                                    {
                                                        "name": "Ada Obi",
                                                        "email": "ada@yourdomain.com"
                                                    }
                                                ],
                                                "cc": [],
                                                "received_at": "2026-10-11T09:14:02+00:00",
                                                "size": 18432,
                                                "has_attachment": true,
                                                "is_read": false,
                                                "is_starred": false,
                                                "is_answered": false,
                                                "is_draft": false,
                                                "keywords": [],
                                                "preview": "Attached are the Q3 figures we discussed.",
                                                "thread_id": "1a2b3c",
                                                "message_id": "<CAJ9x2Q@mail.example.com>"
                                            }
                                        ],
                                        "total": 1284,
                                        "offset": 0,
                                        "limit": 50,
                                        "has_more": true
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No folder by that name.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/files": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List every file",
                "description": "Every attachment in the mailbox, as one list you can search and filter: by name (`q`), `kind`, `person`, `direction` (received or sent), date range (`since`, `until`), size, and `sort`. Page with `cursor`: pass back `next_cursor` until it is null.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "mailbox_files_api_v1_mailbox_files_get",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "maxLength": 200
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Q"
                        }
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "maxLength": 20
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Kind"
                        }
                    },
                    {
                        "name": "person",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "maxLength": 320
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Person"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "pattern": "^(received|sent)$"
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Direction"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Since"
                        }
                    },
                    {
                        "name": "until",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Until"
                        }
                    },
                    {
                        "name": "min_size",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Min Size"
                        }
                    },
                    {
                        "name": "max_size",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Max Size"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^(newest|oldest|largest|smallest|name)$",
                            "default": "newest",
                            "title": "Sort"
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0,
                            "title": "Cursor"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 200,
                            "minimum": 1,
                            "default": 50,
                            "title": "Limit"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "files": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "folder": {
                                                                        "type": "string"
                                                                    },
                                                                    "direction": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "received",
                                                                            "sent"
                                                                        ]
                                                                    },
                                                                    "index": {
                                                                        "type": "integer"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "type": {
                                                                        "type": "string"
                                                                    },
                                                                    "kind": {
                                                                        "type": "string",
                                                                        "description": "images, pdfs, documents, spreadsheets, presentations, archives, media or other."
                                                                    },
                                                                    "size": {
                                                                        "type": "integer"
                                                                    },
                                                                    "subject": {
                                                                        "type": "string"
                                                                    },
                                                                    "from": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "name": {
                                                                                "type": [
                                                                                    "string",
                                                                                    "null"
                                                                                ]
                                                                            },
                                                                            "email": {
                                                                                "type": "string"
                                                                            }
                                                                        },
                                                                        "required": [
                                                                            "email"
                                                                        ]
                                                                    },
                                                                    "to": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "name": {
                                                                                "type": [
                                                                                    "string",
                                                                                    "null"
                                                                                ]
                                                                            },
                                                                            "email": {
                                                                                "type": "string"
                                                                            }
                                                                        },
                                                                        "required": [
                                                                            "email"
                                                                        ]
                                                                    },
                                                                    "received_at": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "next_cursor": {
                                                            "type": [
                                                                "integer",
                                                                "null"
                                                            ]
                                                        },
                                                        "total": {
                                                            "type": "integer"
                                                        },
                                                        "total_messages": {
                                                            "type": "integer"
                                                        },
                                                        "scanned": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Files retrieved successfully",
                                    "data": {
                                        "files": [
                                            {
                                                "id": "INBOX:4821/1",
                                                "message_id": "INBOX:4821",
                                                "folder": "INBOX",
                                                "direction": "received",
                                                "index": 1,
                                                "name": "q3-figures.pdf",
                                                "type": "application/pdf",
                                                "kind": "pdfs",
                                                "size": 248311,
                                                "subject": "Re: the quarterly numbers",
                                                "from": {
                                                    "name": "Tunde Bello",
                                                    "email": "tunde@example.com"
                                                },
                                                "to": {
                                                    "name": "Ada Obi",
                                                    "email": "ada@yourdomain.com"
                                                },
                                                "received_at": "2026-10-11T09:14:02+00:00"
                                            }
                                        ],
                                        "next_cursor": 50,
                                        "total": 316,
                                        "total_messages": 1696,
                                        "scanned": 1696
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/files/summary": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Files at a glance",
                "description": "Totals for the mailbox's files: by kind, by month, top senders, and the largest.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "mailbox_files_summary_api_v1_mailbox_files_summary_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "total_files": {
                                                            "type": "integer"
                                                        },
                                                        "total_bytes": {
                                                            "type": "integer"
                                                        },
                                                        "received": {
                                                            "type": "object",
                                                            "properties": {
                                                                "count": {
                                                                    "type": "integer"
                                                                },
                                                                "bytes": {
                                                                    "type": "integer"
                                                                }
                                                            }
                                                        },
                                                        "sent": {
                                                            "type": "object",
                                                            "properties": {
                                                                "count": {
                                                                    "type": "integer"
                                                                },
                                                                "bytes": {
                                                                    "type": "integer"
                                                                }
                                                            }
                                                        },
                                                        "last_30_days": {
                                                            "type": "integer"
                                                        },
                                                        "by_kind": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "kind": {
                                                                        "type": "string"
                                                                    },
                                                                    "count": {
                                                                        "type": "integer"
                                                                    },
                                                                    "bytes": {
                                                                        "type": "integer"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "top_senders": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "name": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "email": {
                                                                        "type": "string"
                                                                    },
                                                                    "count": {
                                                                        "type": "integer"
                                                                    },
                                                                    "bytes": {
                                                                        "type": "integer"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "by_month": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "month": {
                                                                        "type": "string",
                                                                        "description": "YYYY-MM."
                                                                    },
                                                                    "count": {
                                                                        "type": "integer"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "largest": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "message_id": {
                                                                        "type": "string"
                                                                    },
                                                                    "folder": {
                                                                        "type": "string"
                                                                    },
                                                                    "direction": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "received",
                                                                            "sent"
                                                                        ]
                                                                    },
                                                                    "index": {
                                                                        "type": "integer"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "type": {
                                                                        "type": "string"
                                                                    },
                                                                    "kind": {
                                                                        "type": "string",
                                                                        "description": "images, pdfs, documents, spreadsheets, presentations, archives, media or other."
                                                                    },
                                                                    "size": {
                                                                        "type": "integer"
                                                                    },
                                                                    "subject": {
                                                                        "type": "string"
                                                                    },
                                                                    "from": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "name": {
                                                                                "type": [
                                                                                    "string",
                                                                                    "null"
                                                                                ]
                                                                            },
                                                                            "email": {
                                                                                "type": "string"
                                                                            }
                                                                        },
                                                                        "required": [
                                                                            "email"
                                                                        ]
                                                                    },
                                                                    "to": {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "name": {
                                                                                "type": [
                                                                                    "string",
                                                                                    "null"
                                                                                ]
                                                                            },
                                                                            "email": {
                                                                                "type": "string"
                                                                            }
                                                                        },
                                                                        "required": [
                                                                            "email"
                                                                        ]
                                                                    },
                                                                    "received_at": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "newest_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "oldest_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "File overview retrieved successfully",
                                    "data": {
                                        "total_files": 316,
                                        "total_bytes": 412339200,
                                        "received": {
                                            "count": 281,
                                            "bytes": 377000000
                                        },
                                        "sent": {
                                            "count": 35,
                                            "bytes": 35339200
                                        },
                                        "last_30_days": 22,
                                        "by_kind": [
                                            {
                                                "kind": "pdfs",
                                                "count": 140,
                                                "bytes": 210000000
                                            }
                                        ],
                                        "top_senders": [
                                            {
                                                "name": "Tunde Bello",
                                                "email": "tunde@example.com",
                                                "count": 31,
                                                "bytes": 52000000
                                            }
                                        ],
                                        "by_month": [
                                            {
                                                "month": "2026-10",
                                                "count": 22
                                            }
                                        ],
                                        "largest": [
                                            {
                                                "id": "INBOX:4821/1",
                                                "message_id": "INBOX:4821",
                                                "folder": "INBOX",
                                                "direction": "received",
                                                "index": 1,
                                                "name": "q3-figures.pdf",
                                                "type": "application/pdf",
                                                "kind": "pdfs",
                                                "size": 248311,
                                                "subject": "Re: the quarterly numbers",
                                                "from": {
                                                    "name": "Tunde Bello",
                                                    "email": "tunde@example.com"
                                                },
                                                "to": {
                                                    "name": "Ada Obi",
                                                    "email": "ada@yourdomain.com"
                                                },
                                                "received_at": "2026-10-11T09:14:02+00:00"
                                            }
                                        ],
                                        "newest_at": "2026-10-11T09:14:02+00:00",
                                        "oldest_at": "2024-02-01T12:00:00+00:00"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/draft": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Save a draft",
                "description": "Saves (or, with `replace_id`, replaces) a draft in Drafts. Same fields as a send, JSON or multipart. Autosave by sending `replace_id` each time: the old copy is removed and the new id returned.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | A field is invalid, or `keep_attachments needs replace_id`. |",
                "operationId": "save_draft_api_v1_mailbox_messages_draft_post",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "to": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Recipient addresses. At least one recipient across `to`, `cc` and `bcc`."
                                    },
                                    "cc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Copy recipients: everyone sees them."
                                    },
                                    "bcc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Blind copies: delivered, but no recipient sees them."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "description": "The subject line."
                                    },
                                    "body_text": {
                                        "type": "string",
                                        "description": "The plain-text body. Send this, `body_html`, or both."
                                    },
                                    "body_html": {
                                        "type": "string",
                                        "description": "The HTML body."
                                    },
                                    "in_reply_to": {
                                        "type": "string",
                                        "description": "The Message-ID being answered, to thread the reply."
                                    },
                                    "in_reply_to_id": {
                                        "type": "string",
                                        "description": "That message's id here (`INBOX:4821`), so it is flagged answered."
                                    },
                                    "references": {
                                        "type": "string",
                                        "description": "The References header of the message being answered."
                                    },
                                    "from": {
                                        "type": "string",
                                        "description": "A shared mailbox to send as; must be one this mailbox may send from (see capabilities)."
                                    },
                                    "forward_attachments_from": {
                                        "type": "string",
                                        "description": "Forwarding: the message id whose attachments to include."
                                    },
                                    "attachment_indexes": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "description": "Forwarding: which of its attachments (from its `attachments`)."
                                    },
                                    "attachments": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        },
                                        "description": "Files, multipart only: up to 20, 25 MB in total."
                                    },
                                    "replace_id": {
                                        "type": "string",
                                        "description": "The draft this one replaces."
                                    },
                                    "keep_attachments": {
                                        "type": "boolean",
                                        "description": "Keep the replaced draft's attachments (needs `replace_id`)."
                                    }
                                }
                            },
                            "example": {
                                "to": [
                                    "tunde@example.com"
                                ],
                                "subject": "The Q3 figures",
                                "body_html": "<p>Hi Tunde,</p>",
                                "replace_id": "Drafts:30"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "to": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Recipient addresses. At least one recipient across `to`, `cc` and `bcc`."
                                    },
                                    "cc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Copy recipients: everyone sees them."
                                    },
                                    "bcc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Blind copies: delivered, but no recipient sees them."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "description": "The subject line."
                                    },
                                    "body_text": {
                                        "type": "string",
                                        "description": "The plain-text body. Send this, `body_html`, or both."
                                    },
                                    "body_html": {
                                        "type": "string",
                                        "description": "The HTML body."
                                    },
                                    "in_reply_to": {
                                        "type": "string",
                                        "description": "The Message-ID being answered, to thread the reply."
                                    },
                                    "in_reply_to_id": {
                                        "type": "string",
                                        "description": "That message's id here (`INBOX:4821`), so it is flagged answered."
                                    },
                                    "references": {
                                        "type": "string",
                                        "description": "The References header of the message being answered."
                                    },
                                    "from": {
                                        "type": "string",
                                        "description": "A shared mailbox to send as; must be one this mailbox may send from (see capabilities)."
                                    },
                                    "forward_attachments_from": {
                                        "type": "string",
                                        "description": "Forwarding: the message id whose attachments to include."
                                    },
                                    "attachment_indexes": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "description": "Forwarding: which of its attachments (from its `attachments`)."
                                    },
                                    "attachments": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        },
                                        "description": "Files, multipart only: up to 20, 25 MB in total."
                                    },
                                    "replace_id": {
                                        "type": "string",
                                        "description": "The draft this one replaces."
                                    },
                                    "keep_attachments": {
                                        "type": "boolean",
                                        "description": "Keep the replaced draft's attachments (needs `replace_id`)."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "folder": {
                                                            "type": "string"
                                                        },
                                                        "attachments": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "index": {
                                                                        "type": "integer",
                                                                        "description": "Position in the message; pass it to the attachment download."
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "type": {
                                                                        "type": "string",
                                                                        "description": "MIME type, e.g. `application/pdf`."
                                                                    },
                                                                    "size": {
                                                                        "type": "integer",
                                                                        "description": "Bytes."
                                                                    },
                                                                    "is_inline": {
                                                                        "type": "boolean",
                                                                        "description": "An image shown inside the body (a `cid:` reference) rather than a file."
                                                                    },
                                                                    "content_id": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "description": "The `cid:` the body refers to, for inline images."
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Draft saved",
                                    "data": {
                                        "id": "Drafts:31",
                                        "folder": "Drafts",
                                        "attachments": []
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "A field is invalid, or `keep_attachments needs replace_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/draft/{message_id}": {
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Discard a draft",
                "description": "Permanently removes a draft. Allowed outside Trash because a draft the author just discarded was never delivered mail \u2014 and for that reason refused (409 `not_a_draft`) for anything not in the Drafts folder.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | The id is malformed or is not a draft. |",
                "operationId": "discard_draft_api_v1_mailbox_messages_draft__message_id__delete",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Discarded.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Draft discarded"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The id is malformed or is not a draft.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/scheduled": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List scheduled emails",
                "description": "Emails waiting to be sent at a set time, soonest first.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "scheduled_messages_api_v1_mailbox_messages_scheduled_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "messages": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "folder": {
                                                                        "type": "string"
                                                                    },
                                                                    "send_at": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "description": "pending, sending or failed (a failed send is retried)."
                                                                    },
                                                                    "attempts": {
                                                                        "type": "integer"
                                                                    },
                                                                    "error": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "created_at": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Scheduled messages",
                                    "data": {
                                        "messages": [
                                            {
                                                "id": "Scheduled:7",
                                                "folder": "Scheduled",
                                                "send_at": "2026-10-12T08:00:00+00:00",
                                                "status": "pending",
                                                "attempts": 0,
                                                "error": null,
                                                "created_at": "2026-10-11T16:20:00+00:00"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/scheduled/{message_id}": {
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Cancel a scheduled email",
                "description": "Stops it from being sent and moves it to Drafts, where it can be edited and sent again.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | `That message is not scheduled` (it may already have gone). |",
                "operationId": "cancel_scheduled_api_v1_mailbox_messages_scheduled__message_id__delete",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "Its id in Drafts."
                                                        },
                                                        "folder": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Send cancelled. The message is in Drafts.",
                                    "data": {
                                        "id": "Drafts:32",
                                        "folder": "Drafts"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "`That message is not scheduled` (it may already have gone).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/bulk": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Do one thing to many messages",
                "description": "Applies one action to up to 500 messages: `mark_read`, `mark_unread`, `star`, `unstar`, `move` (needs `folder`), `trash`, `delete` (only messages already in Trash) or `labels` (needs `add` or `remove`). Each message succeeds or fails on its own; `results` says which, in the order you sent them, with `new_id` for messages that moved.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | `move needs a folder`, `labels needs add or remove`, or more than 500 ids. |\n| `404` | A message or the target folder was not found. |",
                "operationId": "bulk_messages_api_v1_mailbox_messages_bulk_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "ids": {
                                        "items": {
                                            "type": "string",
                                            "maxLength": 1024
                                        },
                                        "type": "array",
                                        "maxItems": 500,
                                        "minItems": 1,
                                        "title": "Ids",
                                        "description": "Message ids (`INBOX:4821`), 1 to 500."
                                    },
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "mark_read",
                                            "mark_unread",
                                            "star",
                                            "unstar",
                                            "move",
                                            "trash",
                                            "delete",
                                            "labels"
                                        ],
                                        "title": "Action",
                                        "description": "What to do to every message."
                                    },
                                    "folder": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 255
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Folder",
                                        "description": "For `move`: the folder to move them to."
                                    },
                                    "add": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array",
                                        "maxItems": 20,
                                        "title": "Add",
                                        "description": "For `labels`: labels to add, up to 20."
                                    },
                                    "remove": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array",
                                        "maxItems": 20,
                                        "title": "Remove",
                                        "description": "For `labels`: labels to remove, up to 20."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "ids",
                                    "action"
                                ],
                                "title": "BulkRequest"
                            },
                            "example": {
                                "ids": [
                                    "INBOX:4821",
                                    "INBOX:4820"
                                ],
                                "action": "move",
                                "folder": "Clients"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "results": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "ok": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "new_id": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "description": "The new id after a move or trash."
                                                                    },
                                                                    "error_code": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "message": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "succeeded": {
                                                            "type": "integer"
                                                        },
                                                        "failed": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "2 of 2 messages moved",
                                    "data": {
                                        "results": [
                                            {
                                                "id": "INBOX:4821",
                                                "ok": true,
                                                "new_id": "Clients:89"
                                            },
                                            {
                                                "id": "INBOX:4820",
                                                "ok": true,
                                                "new_id": "Clients:90"
                                            }
                                        ],
                                        "succeeded": 2,
                                        "failed": 0
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`move needs a folder`, `labels needs add or remove`, or more than 500 ids.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "A message or the target folder was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/attachments": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List a message's attachments",
                "operationId": "message_attachments_api_v1_mailbox_messages__message_id__attachments_get",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "index": {
                                                                "type": "integer",
                                                                "description": "Position in the message; pass it to the attachment download."
                                                            },
                                                            "name": {
                                                                "type": "string"
                                                            },
                                                            "type": {
                                                                "type": "string",
                                                                "description": "MIME type, e.g. `application/pdf`."
                                                            },
                                                            "size": {
                                                                "type": "integer",
                                                                "description": "Bytes."
                                                            },
                                                            "is_inline": {
                                                                "type": "boolean",
                                                                "description": "An image shown inside the body (a `cid:` reference) rather than a file."
                                                            },
                                                            "content_id": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "description": "The `cid:` the body refers to, for inline images."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Attachments retrieved successfully",
                                    "data": [
                                        {
                                            "index": 1,
                                            "name": "q3-figures.pdf",
                                            "type": "application/pdf",
                                            "size": 248311,
                                            "is_inline": false,
                                            "content_id": null
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/attachments/{index}": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Download an attachment",
                "description": "The file itself, not JSON: the body is the attachment's bytes, with its `Content-Type` and a `Content-Disposition` carrying the file name. `index` comes from the message's `attachments`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | `Message not found` or `Attachment not found`. |",
                "operationId": "message_attachment_api_v1_mailbox_messages__message_id__attachments__index__get",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    },
                    {
                        "name": "index",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "title": "Index"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The file's bytes.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "`Message not found` or `Attachment not found`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/raw": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Download the original message",
                "description": "The message exactly as received (RFC 822, `message/rfc822`), headers and all \u2014 for \"show original\" or archiving.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |",
                "operationId": "message_raw_api_v1_mailbox_messages__message_id__raw_get",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The raw message bytes.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/labels": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Add or remove labels",
                "description": "Adds and removes labels on one message in a single call. Labels are tidied: lower case, spaces become `_`, other symbols are dropped, 40 characters at most. System flags such as `\\Seen` are refused (use mark-read).\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | Neither `add` nor `remove` has a valid label. |\n| `404` | Message not found. |",
                "operationId": "message_labels_api_v1_mailbox_messages__message_id__labels_post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "add": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array",
                                        "maxItems": 20,
                                        "title": "Add",
                                        "description": "Labels to add, up to 20."
                                    },
                                    "remove": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array",
                                        "maxItems": 20,
                                        "title": "Remove",
                                        "description": "Labels to remove, up to 20."
                                    }
                                },
                                "type": "object",
                                "title": "LabelsRequest"
                            },
                            "example": {
                                "add": [
                                    "invoices"
                                ],
                                "remove": [
                                    "follow-up"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "added": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "removed": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Labels updated",
                                    "data": {
                                        "added": [
                                            "invoices"
                                        ],
                                        "removed": [
                                            "follow-up"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Neither `add` nor `remove` has a valid label.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/labels": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List labels in use",
                "description": "The labels on messages in this mailbox, for a filter or a label picker.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "labels_list_api_v1_mailbox_labels_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "labels": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Labels retrieved successfully",
                                    "data": {
                                        "labels": [
                                            "clients",
                                            "follow-up",
                                            "invoices"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/mark-read": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Mark a message read",
                "operationId": "message_mark_read_api_v1_mailbox_messages__message_id__mark_read_post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Done.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message updated"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "No body. Doing it twice is harmless. To change many at once, use `POST /messages/bulk`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/mark-unread": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Mark a message unread",
                "operationId": "message_mark_unread_api_v1_mailbox_messages__message_id__mark_unread_post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Done.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message updated"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "No body. Doing it twice is harmless. To change many at once, use `POST /messages/bulk`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/star": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Star a message",
                "operationId": "message_star_api_v1_mailbox_messages__message_id__star_post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Done.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message updated"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "No body. Doing it twice is harmless. To change many at once, use `POST /messages/bulk`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/unstar": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Unstar a message",
                "operationId": "message_unstar_api_v1_mailbox_messages__message_id__unstar_post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Done.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message updated"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "No body. Doing it twice is harmless. To change many at once, use `POST /messages/bulk`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/move": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Move a message",
                "operationId": "message_move_api_v1_mailbox_messages__message_id__move_post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "minLength": 1,
                                        "title": "Folder",
                                        "description": "The folder to move it to (its `name`)."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "folder"
                                ],
                                "title": "MoveRequest"
                            },
                            "example": {
                                "folder": "Clients"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "The message's new id."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message moved",
                                    "data": {
                                        "id": "Clients:88"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "No folder by that name, or the message is already there.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Moves the message to another folder. **Its id changes** (a new folder and uid): use the `id` in the answer from now on.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | No folder by that name, or the message is already there. |\n| `404` | Message not found. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/trash": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Move a message to Trash",
                "description": "No body. The message's id changes; use the `id` in the answer. Already in Trash: nothing changes.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |",
                "operationId": "message_trash_api_v1_mailbox_messages__message_id__trash_post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message moved to Trash",
                                    "data": {
                                        "id": "Trash:310"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}": {
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Delete a message for good",
                "description": "Permanently deletes a message that is already in Trash. Cannot be undone. Anywhere else, move it to Trash first.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |\n| `409` | `Move the message to Trash before deleting it permanently`. |",
                "operationId": "message_destroy_api_v1_mailbox_messages__message_id__delete",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message deleted permanently"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "`Move the message to Trash before deleting it permanently`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read a message",
                "description": "One message in full: headers, text and HTML bodies, attachments, and how it was authenticated. Reading it does not mark it read; call mark-read for that.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | No message with that id (it may have been moved; ids change when a message moves). |",
                "operationId": "message_detail_api_v1_mailbox_messages__message_id__get",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "This message's id: `folder:uid`, e.g. `INBOX:4821`. Use it in every per-message call."
                                                        },
                                                        "folder": {
                                                            "type": "string"
                                                        },
                                                        "subject": {
                                                            "type": "string"
                                                        },
                                                        "from": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "name": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "email": {
                                                                        "type": "string"
                                                                    }
                                                                },
                                                                "required": [
                                                                    "email"
                                                                ]
                                                            }
                                                        },
                                                        "to": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "name": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "email": {
                                                                        "type": "string"
                                                                    }
                                                                },
                                                                "required": [
                                                                    "email"
                                                                ]
                                                            }
                                                        },
                                                        "cc": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "name": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "email": {
                                                                        "type": "string"
                                                                    }
                                                                },
                                                                "required": [
                                                                    "email"
                                                                ]
                                                            }
                                                        },
                                                        "received_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "ISO 8601 with offset."
                                                        },
                                                        "size": {
                                                            "type": "integer",
                                                            "description": "Bytes."
                                                        },
                                                        "has_attachment": {
                                                            "type": "boolean"
                                                        },
                                                        "is_read": {
                                                            "type": "boolean"
                                                        },
                                                        "is_starred": {
                                                            "type": "boolean"
                                                        },
                                                        "is_answered": {
                                                            "type": "boolean"
                                                        },
                                                        "is_draft": {
                                                            "type": "boolean"
                                                        },
                                                        "keywords": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "description": "Labels on this message."
                                                        },
                                                        "preview": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The first line or two of text."
                                                        },
                                                        "thread_id": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "message_id": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The RFC 5322 Message-ID header."
                                                        },
                                                        "body_text": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The plain-text body."
                                                        },
                                                        "body_html": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The HTML body, sanitised. Remote images are not loaded."
                                                        },
                                                        "references": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "in_reply_to": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "attachments": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "index": {
                                                                        "type": "integer",
                                                                        "description": "Position in the message; pass it to the attachment download."
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "type": {
                                                                        "type": "string",
                                                                        "description": "MIME type, e.g. `application/pdf`."
                                                                    },
                                                                    "size": {
                                                                        "type": "integer",
                                                                        "description": "Bytes."
                                                                    },
                                                                    "is_inline": {
                                                                        "type": "boolean",
                                                                        "description": "An image shown inside the body (a `cid:` reference) rather than a file."
                                                                    },
                                                                    "content_id": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ],
                                                                        "description": "The `cid:` the body refers to, for inline images."
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "mailed_by": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The sending server's domain."
                                                        },
                                                        "signed_by": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The DKIM signing domain."
                                                        },
                                                        "authentication": {
                                                            "type": "object",
                                                            "properties": {
                                                                "spf": {
                                                                    "type": [
                                                                        "string",
                                                                        "null"
                                                                    ]
                                                                },
                                                                "dkim": {
                                                                    "type": [
                                                                        "string",
                                                                        "null"
                                                                    ]
                                                                },
                                                                "dmarc": {
                                                                    "type": [
                                                                        "string",
                                                                        "null"
                                                                    ]
                                                                }
                                                            },
                                                            "description": "What the receiving server recorded."
                                                        },
                                                        "list_unsubscribe": {
                                                            "type": "object",
                                                            "properties": {
                                                                "mailto": {
                                                                    "type": [
                                                                        "string",
                                                                        "null"
                                                                    ]
                                                                },
                                                                "url": {
                                                                    "type": [
                                                                        "string",
                                                                        "null"
                                                                    ]
                                                                },
                                                                "one_click": {
                                                                    "type": "boolean"
                                                                }
                                                            },
                                                            "description": "Present for mailing-list mail."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message retrieved successfully",
                                    "data": {
                                        "id": "INBOX:4821",
                                        "folder": "INBOX",
                                        "subject": "Re: the quarterly numbers",
                                        "from": [
                                            {
                                                "name": "Tunde Bello",
                                                "email": "tunde@example.com"
                                            }
                                        ],
                                        "to": [
                                            {
                                                "name": "Ada Obi",
                                                "email": "ada@yourdomain.com"
                                            }
                                        ],
                                        "cc": [],
                                        "received_at": "2026-10-11T09:14:02+00:00",
                                        "size": 18432,
                                        "has_attachment": true,
                                        "is_read": false,
                                        "is_starred": false,
                                        "is_answered": false,
                                        "is_draft": false,
                                        "keywords": [],
                                        "preview": "Attached are the Q3 figures we discussed.",
                                        "thread_id": "1a2b3c",
                                        "message_id": "<CAJ9x2Q@mail.example.com>",
                                        "body_text": "Hi Ada,\n\nAttached are the Q3 figures we discussed.\n\nTunde",
                                        "body_html": "<p>Hi Ada,</p><p>Attached are the Q3 figures we discussed.</p><p>Tunde</p>",
                                        "references": null,
                                        "in_reply_to": null,
                                        "attachments": [
                                            {
                                                "index": 1,
                                                "name": "q3-figures.pdf",
                                                "type": "application/pdf",
                                                "size": 248311,
                                                "is_inline": false,
                                                "content_id": null
                                            }
                                        ],
                                        "mailed_by": "mail.example.com",
                                        "signed_by": "example.com",
                                        "authentication": {
                                            "spf": "pass",
                                            "dkim": "pass",
                                            "dmarc": "pass"
                                        },
                                        "list_unsubscribe": null
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No message with that id (it may have been moved; ids change when a message moves).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/thread": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read a conversation",
                "description": "Every message in the conversation this one belongs to, oldest first, across folders (your replies in Sent included). Summaries only; read one in full with `GET /messages/{message_id}`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "message_thread_api_v1_mailbox_messages__message_id__thread_get",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string",
                                                                "description": "This message's id: `folder:uid`, e.g. `INBOX:4821`. Use it in every per-message call."
                                                            },
                                                            "folder": {
                                                                "type": "string"
                                                            },
                                                            "subject": {
                                                                "type": "string"
                                                            },
                                                            "from": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "name": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        },
                                                                        "email": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "required": [
                                                                        "email"
                                                                    ]
                                                                }
                                                            },
                                                            "to": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "name": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        },
                                                                        "email": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "required": [
                                                                        "email"
                                                                    ]
                                                                }
                                                            },
                                                            "cc": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "name": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        },
                                                                        "email": {
                                                                            "type": "string"
                                                                        }
                                                                    },
                                                                    "required": [
                                                                        "email"
                                                                    ]
                                                                }
                                                            },
                                                            "received_at": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "description": "ISO 8601 with offset."
                                                            },
                                                            "size": {
                                                                "type": "integer",
                                                                "description": "Bytes."
                                                            },
                                                            "has_attachment": {
                                                                "type": "boolean"
                                                            },
                                                            "is_read": {
                                                                "type": "boolean"
                                                            },
                                                            "is_starred": {
                                                                "type": "boolean"
                                                            },
                                                            "is_answered": {
                                                                "type": "boolean"
                                                            },
                                                            "is_draft": {
                                                                "type": "boolean"
                                                            },
                                                            "keywords": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "string"
                                                                },
                                                                "description": "Labels on this message."
                                                            },
                                                            "preview": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "description": "The first line or two of text."
                                                            },
                                                            "thread_id": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "message_id": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "description": "The RFC 5322 Message-ID header."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Thread retrieved successfully",
                                    "data": [
                                        {
                                            "id": "INBOX:4821",
                                            "folder": "INBOX",
                                            "subject": "Re: the quarterly numbers",
                                            "from": [
                                                {
                                                    "name": "Tunde Bello",
                                                    "email": "tunde@example.com"
                                                }
                                            ],
                                            "to": [
                                                {
                                                    "name": "Ada Obi",
                                                    "email": "ada@yourdomain.com"
                                                }
                                            ],
                                            "cc": [],
                                            "received_at": "2026-10-11T09:14:02+00:00",
                                            "size": 18432,
                                            "has_attachment": true,
                                            "is_read": false,
                                            "is_starred": false,
                                            "is_answered": false,
                                            "is_draft": false,
                                            "keywords": [],
                                            "preview": "Attached are the Q3 figures we discussed.",
                                            "thread_id": "1a2b3c",
                                            "message_id": "<CAJ9x2Q@mail.example.com>"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/contacts": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Suggest recipients",
                "description": "Addresses this mailbox has written to or heard from, most frequent first \u2014 for autocomplete. Saved contacts are under the address book (`/address-book/contacts`).\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "contacts_api_v1_mailbox_contacts_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "name": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "email": {
                                                                "type": "string"
                                                            },
                                                            "count": {
                                                                "type": "integer",
                                                                "description": "How often they appear."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Contacts retrieved successfully",
                                    "data": [
                                        {
                                            "name": "Tunde Bello",
                                            "email": "tunde@example.com",
                                            "count": 42
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/send": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Send an email as the mailbox holder",
                "description": "Sends from this mailbox's own address and files a copy in **Sent**. Send JSON, or `multipart/form-data` when you attach files (repeat a field for each value: `to`, `cc`, `bcc`, `attachments`).\n\n**Retrying safely.** Send an `Idempotency-Key` header of the form `<app>-<ULID>` (for example `crm-01JBT8XQ2M9WYC3K4F6R7S8T9V`; one per email, saved before the first try). A retry with the same key within 24 hours returns the first answer, with `Idempotency-Replayed: true`, instead of sending again; while the first is still sending it answers `409` with `Retry-After`.\n\n**Scheduling.** With `send_at`, the message waits in the Scheduled folder and the answer carries `send_at`; cancel it with `DELETE /messages/scheduled/{id}`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `403` | `You do not have permission to send from that address` (a `from` this mailbox may not use), or read-only access to a shared mailbox. |\n| `409` | A send with this `Idempotency-Key` is still in progress. Wait for `Retry-After`, then retry with the same key. |\n| `422` | `Add at least one valid recipient`, `The message has no content`, too many or too large attachments, an invalid `send_at`, an `Idempotency-Key` that is not `<app>-<ULID>`, or one reused for a different email. |",
                "operationId": "send_message_api_v1_mailbox_messages_send_post",
                "responses": {
                    "200": {
                        "description": "Sent, or scheduled.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The copy in Sent (`Sent:413`), or in Scheduled. Null if it was sent but could not be filed."
                                                        },
                                                        "message_id": {
                                                            "type": "string",
                                                            "description": "The Message-ID the email went out with."
                                                        },
                                                        "answered_id": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The message flagged answered, for a reply."
                                                        },
                                                        "folder": {
                                                            "type": "string",
                                                            "description": "Scheduled only."
                                                        },
                                                        "send_at": {
                                                            "type": "string",
                                                            "description": "Scheduled only."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Message sent",
                                    "data": {
                                        "id": "Sent:413",
                                        "message_id": "<9f86d081.idem@yourdomain.com>",
                                        "answered_id": null
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "`You do not have permission to send from that address` (a `from` this mailbox may not use), or read-only access to a shared mailbox.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "A send with this `Idempotency-Key` is still in progress. Wait for `Retry-After`, then retry with the same key.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`Add at least one valid recipient`, `The message has no content`, too many or too large attachments, an invalid `send_at`, an `Idempotency-Key` that is not `<app>-<ULID>`, or one reused for a different email.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "description": "Makes a retry safe. Must look like `<app>-<ULID>`: your app's name in lowercase, a dash, then a ULID. One per email, sent again on every retry of it. Any other shape is a 422.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "crm-01JBT8XQ2M9WYC3K4F6R7S8T9V"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "to": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Recipient addresses. At least one recipient across `to`, `cc` and `bcc`."
                                    },
                                    "cc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Copy recipients: everyone sees them."
                                    },
                                    "bcc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Blind copies: delivered, but no recipient sees them."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "description": "The subject line."
                                    },
                                    "body_text": {
                                        "type": "string",
                                        "description": "The plain-text body. Send this, `body_html`, or both."
                                    },
                                    "body_html": {
                                        "type": "string",
                                        "description": "The HTML body."
                                    },
                                    "in_reply_to": {
                                        "type": "string",
                                        "description": "The Message-ID being answered, to thread the reply."
                                    },
                                    "in_reply_to_id": {
                                        "type": "string",
                                        "description": "That message's id here (`INBOX:4821`), so it is flagged answered."
                                    },
                                    "references": {
                                        "type": "string",
                                        "description": "The References header of the message being answered."
                                    },
                                    "send_at": {
                                        "type": "string",
                                        "description": "ISO 8601 (UTC). Schedule instead of sending now."
                                    },
                                    "from": {
                                        "type": "string",
                                        "description": "A shared mailbox to send as; must be one this mailbox may send from (see capabilities)."
                                    },
                                    "mentions": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Addresses @-mentioned in the body."
                                    },
                                    "forward_attachments_from": {
                                        "type": "string",
                                        "description": "Forwarding: the message id whose attachments to include."
                                    },
                                    "attachment_indexes": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "description": "Forwarding: which of its attachments (from its `attachments`)."
                                    },
                                    "attachments": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        },
                                        "description": "Files, multipart only: up to 20, 25 MB in total."
                                    }
                                }
                            },
                            "example": {
                                "to": [
                                    "tunde@example.com"
                                ],
                                "subject": "The Q3 figures",
                                "body_text": "Hi Tunde,\n\nThe figures are below.\n\nAda"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "to": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Recipient addresses. At least one recipient across `to`, `cc` and `bcc`."
                                    },
                                    "cc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Copy recipients: everyone sees them."
                                    },
                                    "bcc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Blind copies: delivered, but no recipient sees them."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "description": "The subject line."
                                    },
                                    "body_text": {
                                        "type": "string",
                                        "description": "The plain-text body. Send this, `body_html`, or both."
                                    },
                                    "body_html": {
                                        "type": "string",
                                        "description": "The HTML body."
                                    },
                                    "in_reply_to": {
                                        "type": "string",
                                        "description": "The Message-ID being answered, to thread the reply."
                                    },
                                    "in_reply_to_id": {
                                        "type": "string",
                                        "description": "That message's id here (`INBOX:4821`), so it is flagged answered."
                                    },
                                    "references": {
                                        "type": "string",
                                        "description": "The References header of the message being answered."
                                    },
                                    "send_at": {
                                        "type": "string",
                                        "description": "ISO 8601 (UTC). Schedule instead of sending now."
                                    },
                                    "from": {
                                        "type": "string",
                                        "description": "A shared mailbox to send as; must be one this mailbox may send from (see capabilities)."
                                    },
                                    "mentions": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Addresses @-mentioned in the body."
                                    },
                                    "forward_attachments_from": {
                                        "type": "string",
                                        "description": "Forwarding: the message id whose attachments to include."
                                    },
                                    "attachment_indexes": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "description": "Forwarding: which of its attachments (from its `attachments`)."
                                    },
                                    "attachments": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        },
                                        "description": "Files, multipart only: up to 20, 25 MB in total."
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/settings": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read settings",
                "description": "The mailbox holder's own settings, and storage used.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "settings_show_api_v1_mailbox_settings_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "email_address": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The display name recipients see."
                                                        },
                                                        "signature_html": {
                                                            "type": "string"
                                                        },
                                                        "signature_on_reply": {
                                                            "type": "boolean"
                                                        },
                                                        "display_density": {
                                                            "type": "string",
                                                            "enum": [
                                                                "comfortable",
                                                                "compact"
                                                            ]
                                                        },
                                                        "undo_send_enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "undo_send_seconds": {
                                                            "type": "integer",
                                                            "enum": [
                                                                5,
                                                                10,
                                                                20,
                                                                30
                                                            ]
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "properties": {
                                                                "used_mb": {
                                                                    "type": "number"
                                                                },
                                                                "quota_mb": {
                                                                    "type": "number"
                                                                },
                                                                "percentage": {
                                                                    "type": [
                                                                        "number",
                                                                        "null"
                                                                    ]
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Settings retrieved successfully",
                                    "data": {
                                        "email_address": "ada@yourdomain.com",
                                        "name": "Ada Obi",
                                        "signature_html": "<p>Ada Obi<br>Head of Finance</p>",
                                        "signature_on_reply": true,
                                        "display_density": "comfortable",
                                        "undo_send_enabled": true,
                                        "undo_send_seconds": 10,
                                        "storage": {
                                            "used_mb": 812.4,
                                            "quota_mb": 5120,
                                            "percentage": 15.9
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Update settings",
                "description": "Send only what changes. `undo_send_seconds` is 5, 10, 20 or 30; `display_density` is `comfortable` or `compact`. Answers with all settings.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | A blank display name, an unknown display density, or an undo window that is not 5, 10, 20 or 30. |",
                "operationId": "settings_update_api_v1_mailbox_settings_put",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "anyOf": [
                                            {
                                                "type": "string"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Name",
                                        "description": "The display name recipients see. Cannot be blank."
                                    },
                                    "signature_html": {
                                        "anyOf": [
                                            {
                                                "type": "string"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Signature Html",
                                        "description": "The signature, as HTML."
                                    },
                                    "signature_on_reply": {
                                        "anyOf": [
                                            {
                                                "type": "boolean"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Signature On Reply",
                                        "description": "Add the signature to replies and forwards too."
                                    },
                                    "display_density": {
                                        "anyOf": [
                                            {
                                                "type": "string"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Display Density",
                                        "description": "`comfortable` or `compact`."
                                    },
                                    "undo_send_enabled": {
                                        "anyOf": [
                                            {
                                                "type": "boolean"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Undo Send Enabled",
                                        "description": "Hold each send briefly so it can be undone."
                                    },
                                    "undo_send_seconds": {
                                        "anyOf": [
                                            {
                                                "type": "integer"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Undo Send Seconds",
                                        "description": "How long: 5, 10, 20 or 30."
                                    }
                                },
                                "type": "object",
                                "title": "UpdateSettingsRequest"
                            },
                            "example": {
                                "name": "Ada Obi",
                                "signature_on_reply": true,
                                "undo_send_seconds": 10
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "email_address": {
                                                            "type": "string"
                                                        },
                                                        "name": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "The display name recipients see."
                                                        },
                                                        "signature_html": {
                                                            "type": "string"
                                                        },
                                                        "signature_on_reply": {
                                                            "type": "boolean"
                                                        },
                                                        "display_density": {
                                                            "type": "string",
                                                            "enum": [
                                                                "comfortable",
                                                                "compact"
                                                            ]
                                                        },
                                                        "undo_send_enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "undo_send_seconds": {
                                                            "type": "integer",
                                                            "enum": [
                                                                5,
                                                                10,
                                                                20,
                                                                30
                                                            ]
                                                        },
                                                        "storage": {
                                                            "type": "object",
                                                            "properties": {
                                                                "used_mb": {
                                                                    "type": "number"
                                                                },
                                                                "quota_mb": {
                                                                    "type": "number"
                                                                },
                                                                "percentage": {
                                                                    "type": [
                                                                        "number",
                                                                        "null"
                                                                    ]
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Settings updated successfully",
                                    "data": {
                                        "email_address": "ada@yourdomain.com",
                                        "name": "Ada Obi",
                                        "signature_html": "<p>Ada Obi<br>Head of Finance</p>",
                                        "signature_on_reply": true,
                                        "display_density": "comfortable",
                                        "undo_send_enabled": true,
                                        "undo_send_seconds": 10,
                                        "storage": {
                                            "used_mb": 812.4,
                                            "quota_mb": 5120,
                                            "percentage": 15.9
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "A blank display name, an unknown display density, or an undo window that is not 5, 10, 20 or 30.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/security": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read security settings",
                "description": "Whether two-factor sign-in is on, and how many recovery codes are left.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "security_show_api_v1_mailbox_security_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "two_factor_enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "two_factor_confirmed_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "two_factor_pending": {
                                                            "type": "boolean",
                                                            "description": "Enrolment started, not yet confirmed."
                                                        },
                                                        "recovery_codes_remaining": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Security retrieved successfully",
                                    "data": {
                                        "two_factor_enabled": true,
                                        "two_factor_confirmed_at": "2026-09-20T12:00:00+00:00",
                                        "two_factor_pending": false,
                                        "recovery_codes_remaining": 8
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/security/2fa/begin": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Start two-factor setup",
                "description": "No body. Returns a secret and a QR code for an authenticator app, and one-time recovery codes. Show the codes once; then confirm with `POST /security/2fa/confirm`. Nothing changes until it is confirmed.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | `Could not start enrolment` (for example, two-factor is already on). |",
                "operationId": "two_factor_begin_api_v1_mailbox_security_2fa_begin_post",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "secret": {
                                                            "type": "string"
                                                        },
                                                        "qr_code_svg": {
                                                            "type": "string",
                                                            "description": "An SVG image to show."
                                                        },
                                                        "recovery_codes": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Enrolment started",
                                    "data": {
                                        "secret": "JBSWY3DPEHPK3PXP",
                                        "qr_code_svg": "<svg ...>",
                                        "recovery_codes": [
                                            "8f3k-2m9q",
                                            "p4x7-1c6z"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`Could not start enrolment` (for example, two-factor is already on).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/security/2fa/confirm": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Turn two-factor on",
                "operationId": "two_factor_confirm_api_v1_mailbox_security_2fa_confirm_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "minLength": 4,
                                        "title": "Code",
                                        "description": "The current 6-digit code from the authenticator app."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "code"
                                ],
                                "title": "TwoFactorCodeRequest"
                            },
                            "example": {
                                "code": "492039"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "two_factor_enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "two_factor_confirmed_at": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Two-factor authentication enabled",
                                    "data": {
                                        "two_factor_enabled": true,
                                        "two_factor_confirmed_at": "2026-10-11T12:00:00+00:00"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The code is wrong or expired.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Confirms setup with the current code from the authenticator app. From then on, sign-in needs a code.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | The code is wrong or expired. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/security/2fa/disable": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Turn two-factor off",
                "description": "Needs a current code (or a recovery code), so a stolen session alone cannot turn it off.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | The code is wrong. |",
                "operationId": "two_factor_disable_api_v1_mailbox_security_2fa_disable_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "minLength": 4,
                                        "title": "Code",
                                        "description": "A current code, or a recovery code."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "code"
                                ],
                                "title": "TwoFactorCodeRequest"
                            },
                            "example": {
                                "code": "492039"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "two_factor_enabled": {
                                                            "type": "boolean"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Two-factor authentication disabled",
                                    "data": {
                                        "two_factor_enabled": false
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The code is wrong.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/security/sessions": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List signed-in devices",
                "operationId": "security_sessions_api_v1_mailbox_security_sessions_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string"
                                                            },
                                                            "signed_in_at": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "expires_at": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "ip_address": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "user_agent": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "revoked": {
                                                                "type": "boolean"
                                                            },
                                                            "active": {
                                                                "type": "boolean"
                                                            },
                                                            "current": {
                                                                "type": "boolean",
                                                                "description": "The session making this call."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Sessions retrieved successfully",
                                    "data": [
                                        {
                                            "id": "01J9ZQ0A1B2C3D4E5F6G7H8J9K",
                                            "signed_in_at": "2026-10-11T08:00:00+00:00",
                                            "expires_at": "2026-10-18T08:00:00+00:00",
                                            "ip_address": "102.89.0.10",
                                            "user_agent": "Mailyte/2.1 (iOS)",
                                            "revoked": false,
                                            "active": true,
                                            "current": true
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Every session for this mailbox, newest first. `current` marks the one making the call.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/security/sessions/{session_id}": {
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Sign out another device",
                "description": "Ends another session. To end your own, use `POST /mailbox-auth/logout`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Session not found. |\n| `409` | `Use sign out to end the session you are using`. |",
                "operationId": "security_revoke_session_api_v1_mailbox_security_sessions__session_id__delete",
                "parameters": [
                    {
                        "name": "session_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Session Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Signed out.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Session signed out"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Session not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "`Use sign out to end the session you are using`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/compose": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Draft an email with AI",
                "description": "Writes or rewrites a draft from an instruction. Only when `capabilities.ai` is true and the holder has accepted the AI terms (`POST /ai/consent`).\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `502` | The AI service did not answer usefully. |\n| `503` | No AI is set up on this server. |",
                "operationId": "ai_compose_api_v1_mailbox_ai_compose_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "instruction": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "minLength": 1,
                                        "title": "Instruction",
                                        "description": "What to write, in plain words, up to 2,000 characters."
                                    },
                                    "existing_draft": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 20000
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Existing Draft",
                                        "description": "A draft to rewrite instead of starting fresh."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "instruction"
                                ],
                                "title": "AiComposeRequest"
                            },
                            "example": {
                                "instruction": "Thank Tunde for the figures and ask for the Q4 forecast by Friday.",
                                "existing_draft": null
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "draft": {
                                                            "type": "string"
                                                        },
                                                        "ai_calls_remaining": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Draft generated",
                                    "data": {
                                        "draft": "Hi Tunde,\n\nThank you for the Q3 figures...",
                                        "ai_calls_remaining": 47
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "The AI service did not answer usefully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "No AI is set up on this server.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/summarize/{message_id}": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Summarise an email with AI",
                "description": "No body. Only when `capabilities.ai` is true and the holder has accepted the AI terms (`POST /ai/consent`).\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | The message has no text to summarise. |\n| `502` | The AI service did not answer usefully. |\n| `503` | No AI is set up on this server. |",
                "operationId": "ai_summarize_api_v1_mailbox_ai_summarize__message_id__post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "summary": {
                                                            "type": "string"
                                                        },
                                                        "ai_calls_remaining": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Summary generated",
                                    "data": {
                                        "summary": "Tunde sent the Q3 figures and wants a call this week.",
                                        "ai_calls_remaining": 46
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The message has no text to summarise.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "The AI service did not answer usefully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "No AI is set up on this server.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/forwarding": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read forwarding",
                "operationId": "forwarding_show_api_v1_mailbox_forwarding_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "addresses": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "keep_copy": {
                                                            "type": "boolean",
                                                            "description": "Keep a copy in this mailbox as well."
                                                        },
                                                        "managed": {
                                                            "type": "boolean",
                                                            "description": "True once set through this API."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Forwarding retrieved successfully",
                                    "data": {
                                        "enabled": true,
                                        "addresses": [
                                            "ada.obi@gmail.com"
                                        ],
                                        "keep_copy": true,
                                        "managed": true
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "put": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Set forwarding",
                "description": "Forwards new mail to up to 5 addresses. `keep_copy: false` forwards without keeping a copy here. Send `enabled: false` to stop.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | No address while turning it on, more than 5 addresses, or the mailbox's own address. |",
                "operationId": "forwarding_update_api_v1_mailbox_forwarding_put",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "enabled": {
                                        "type": "boolean",
                                        "title": "Enabled",
                                        "default": false,
                                        "description": "Forward new mail."
                                    },
                                    "addresses": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array",
                                        "title": "Addresses",
                                        "description": "Where to, up to 5. Not this mailbox itself."
                                    },
                                    "keep_copy": {
                                        "type": "boolean",
                                        "title": "Keep Copy",
                                        "default": true,
                                        "description": "Keep a copy here as well."
                                    }
                                },
                                "type": "object",
                                "title": "ForwardingRequest"
                            },
                            "example": {
                                "enabled": true,
                                "addresses": [
                                    "ada.obi@gmail.com"
                                ],
                                "keep_copy": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "addresses": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "keep_copy": {
                                                            "type": "boolean",
                                                            "description": "Keep a copy in this mailbox as well."
                                                        },
                                                        "managed": {
                                                            "type": "boolean",
                                                            "description": "True once set through this API."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Forwarding saved",
                                    "data": {
                                        "enabled": true,
                                        "addresses": [
                                            "ada.obi@gmail.com"
                                        ],
                                        "keep_copy": true,
                                        "managed": true
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "No address while turning it on, more than 5 addresses, or the mailbox's own address.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/rules": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read filter rules",
                "operationId": "rules_show_api_v1_mailbox_rules_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "rules": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "match": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "all",
                                                                            "any"
                                                                        ]
                                                                    },
                                                                    "enabled": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "conditions": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "field": {
                                                                                    "type": "string",
                                                                                    "description": "from, to, cc, subject or body."
                                                                                },
                                                                                "operator": {
                                                                                    "type": "string",
                                                                                    "description": "contains (the default), is, or matches (with * and ? wildcards)."
                                                                                },
                                                                                "value": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    },
                                                                    "actions": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "type": {
                                                                                    "type": "string",
                                                                                    "description": "move (value: a folder), label (value: a label), flag, mark_read, forward (value: an address) or discard."
                                                                                },
                                                                                "value": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Rules retrieved successfully",
                                    "data": {
                                        "rules": [
                                            {
                                                "id": "r1",
                                                "name": "Invoices to Finance",
                                                "match": "any",
                                                "enabled": true,
                                                "conditions": [
                                                    {
                                                        "field": "subject",
                                                        "operator": "contains",
                                                        "value": "invoice"
                                                    }
                                                ],
                                                "actions": [
                                                    {
                                                        "type": "move",
                                                        "value": "Finance"
                                                    }
                                                ]
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "The rules applied to new mail, in order.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "put": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Replace filter rules",
                "operationId": "rules_update_api_v1_mailbox_rules_put",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "rules": {
                                        "items": {
                                            "additionalProperties": true,
                                            "type": "object"
                                        },
                                        "type": "array",
                                        "title": "Rules",
                                        "description": "The whole list, in order. Each rule: `name`, `match` (`all` or `any`), `enabled`, `conditions` and `actions`, as in the response."
                                    }
                                },
                                "type": "object",
                                "title": "RulesRequest"
                            },
                            "example": {
                                "rules": [
                                    {
                                        "name": "Invoices to Finance",
                                        "match": "any",
                                        "enabled": true,
                                        "conditions": [
                                            {
                                                "field": "subject",
                                                "operator": "contains",
                                                "value": "invoice"
                                            }
                                        ],
                                        "actions": [
                                            {
                                                "type": "move",
                                                "value": "Finance"
                                            }
                                        ]
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "rules": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": "string"
                                                                    },
                                                                    "match": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "all",
                                                                            "any"
                                                                        ]
                                                                    },
                                                                    "enabled": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "conditions": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "field": {
                                                                                    "type": "string",
                                                                                    "description": "from, to, cc, subject or body."
                                                                                },
                                                                                "operator": {
                                                                                    "type": "string",
                                                                                    "description": "contains (the default), is, or matches (with * and ? wildcards)."
                                                                                },
                                                                                "value": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    },
                                                                    "actions": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "type": {
                                                                                    "type": "string",
                                                                                    "description": "move (value: a folder), label (value: a label), flag, mark_read, forward (value: an address) or discard."
                                                                                },
                                                                                "value": {
                                                                                    "type": "string"
                                                                                }
                                                                            }
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Rules saved",
                                    "data": {
                                        "rules": [
                                            {
                                                "id": "r1",
                                                "name": "Invoices to Finance",
                                                "match": "any",
                                                "enabled": true,
                                                "conditions": [
                                                    {
                                                        "field": "subject",
                                                        "operator": "contains",
                                                        "value": "invoice"
                                                    }
                                                ],
                                                "actions": [
                                                    {
                                                        "type": "move",
                                                        "value": "Finance"
                                                    }
                                                ]
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "More than 50 rules, or a rule with an unknown field, operator or action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Replaces the whole list (up to 50 rules), in the order given. Send every rule you want to keep.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | More than 50 rules, or a rule with an unknown field, operator or action. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/vacation": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read the vacation reply",
                "operationId": "vacation_show_api_v1_mailbox_vacation_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "subject": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "message": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "start_date": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "YYYY-MM-DD."
                                                        },
                                                        "end_date": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "YYYY-MM-DD."
                                                        },
                                                        "managed": {
                                                            "type": "boolean"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Vacation retrieved successfully",
                                    "data": {
                                        "enabled": false,
                                        "subject": null,
                                        "message": null,
                                        "start_date": null,
                                        "end_date": null,
                                        "managed": true
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "put": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Set the vacation reply",
                "description": "An automatic reply to people who write while you are away, optionally between two dates. Send `enabled: false` to stop it.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `422` | `Write the message to send, or turn the responder off`. |",
                "operationId": "vacation_update_api_v1_mailbox_vacation_put",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "enabled": {
                                        "type": "boolean",
                                        "title": "Enabled",
                                        "default": false,
                                        "description": "Send the automatic reply."
                                    },
                                    "subject": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 500
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Subject",
                                        "description": "The reply's subject."
                                    },
                                    "message": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 20000
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Message",
                                        "description": "The reply's text. Needed to turn it on."
                                    },
                                    "start_date": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 40
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Start Date",
                                        "description": "First day (YYYY-MM-DD), optional."
                                    },
                                    "end_date": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 40
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "End Date",
                                        "description": "Last day (YYYY-MM-DD), optional."
                                    }
                                },
                                "type": "object",
                                "title": "VacationRequest"
                            },
                            "example": {
                                "enabled": true,
                                "subject": "Out of office",
                                "message": "I'm away until 20 October and will reply then.",
                                "start_date": "2026-10-13",
                                "end_date": "2026-10-20"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "subject": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "message": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "start_date": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "YYYY-MM-DD."
                                                        },
                                                        "end_date": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "YYYY-MM-DD."
                                                        },
                                                        "managed": {
                                                            "type": "boolean"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Vacation responder saved",
                                    "data": {
                                        "enabled": true,
                                        "subject": "Out of office",
                                        "message": "I'm away until 20 October and will reply then.",
                                        "start_date": "2026-10-13",
                                        "end_date": "2026-10-20",
                                        "managed": true
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`Write the message to send, or turn the responder off`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/security/password": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Change the password",
                "description": "Changes the mailbox password. Every other session is signed out (the one making the call stays); mail apps need the new password.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `401` | `Current password is incorrect`. |\n| `409` | `New password must be different from the current one`. |\n| `422` | The new password is too weak or too long. |\n| `429` | Too many wrong current passwords. |",
                "operationId": "change_password_api_v1_mailbox_security_password_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "current_password": {
                                        "type": "string",
                                        "maxLength": 1024,
                                        "minLength": 1,
                                        "title": "Current Password",
                                        "description": "The password in use now."
                                    },
                                    "new_password": {
                                        "type": "string",
                                        "maxLength": 1024,
                                        "minLength": 1,
                                        "title": "New Password",
                                        "description": "The new password. Must differ from the current one."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "current_password",
                                    "new_password"
                                ],
                                "title": "PasswordChangeRequest"
                            },
                            "example": {
                                "current_password": "old-password",
                                "new_password": "a-long-new-passphrase"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "sessions_revoked": {
                                                            "type": "integer",
                                                            "description": "Other sessions signed out."
                                                        },
                                                        "cache_flushed": {
                                                            "type": "boolean"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Password changed",
                                    "data": {
                                        "sessions_revoked": 2,
                                        "cache_flushed": true
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "`Current password is incorrect`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "`New password must be different from the current one`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The new password is too weak or too long.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many wrong current passwords.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "The mail server could not be reached, so the password was not checked. Try again."
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/blocked-senders": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List blocked senders",
                "description": "Mail from a blocked address is filed to the Junk folder at delivery, before any rule, forward or vacation reply runs. Nothing is discarded.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "blocked_senders_show_api_v1_mailbox_blocked_senders_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "addresses": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "managed": {
                                                            "type": "boolean"
                                                        },
                                                        "folder": {
                                                            "type": "string",
                                                            "description": "Where their mail goes instead."
                                                        },
                                                        "limit": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Blocked senders retrieved successfully",
                                    "data": {
                                        "addresses": [
                                            "spam@example.net"
                                        ],
                                        "managed": true,
                                        "folder": "Junk",
                                        "limit": 500
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Block a sender",
                "description": "Mail from this address goes straight to Junk. One full address per call (whole domains cannot be blocked); up to 500.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "blocked_senders_add_api_v1_mailbox_blocked_senders_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "address": {
                                        "type": "string",
                                        "maxLength": 320,
                                        "minLength": 3,
                                        "title": "Address",
                                        "description": "The full address to block."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "address"
                                ],
                                "title": "BlockSenderRequest"
                            },
                            "example": {
                                "address": "spam@example.net"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "addresses": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "managed": {
                                                            "type": "boolean"
                                                        },
                                                        "folder": {
                                                            "type": "string",
                                                            "description": "Where their mail goes instead."
                                                        },
                                                        "limit": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Sender blocked",
                                    "data": {
                                        "addresses": [
                                            "spam@example.net"
                                        ],
                                        "managed": true,
                                        "folder": "Junk",
                                        "limit": 500
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/blocked-senders/{address}": {
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Unblock a sender",
                "description": "Removes one address. Unblocking an address that is not blocked is not an error. Mail already filed to Junk stays where it is.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "blocked_senders_remove_api_v1_mailbox_blocked_senders__address__delete",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Address"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "addresses": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "managed": {
                                                            "type": "boolean"
                                                        },
                                                        "folder": {
                                                            "type": "string",
                                                            "description": "Where their mail goes instead."
                                                        },
                                                        "limit": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Sender unblocked",
                                    "data": {
                                        "addresses": [],
                                        "managed": true,
                                        "folder": "Junk",
                                        "limit": 500
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/insights": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Mailbox insights",
                "description": "Patterns in the mailbox over a `window` (`30d`, `90d` default, `180d` or `365d`): what needs attention, how fast replies go out, when mail arrives, who you write to most, and clutter. Each block is left out when there is nothing to say. Results are cached; `refresh=true` recomputes.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `503` | Insights are busy on this server; try again shortly. |",
                "operationId": "insights_api_v1_mailbox_insights_get",
                "parameters": [
                    {
                        "name": "window",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^(30|90|180|365)d$",
                            "default": "90d",
                            "title": "Window"
                        }
                    },
                    {
                        "name": "refresh",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false,
                            "title": "Refresh"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "window": {
                                                            "type": "object",
                                                            "properties": {
                                                                "from": {
                                                                    "type": "string"
                                                                },
                                                                "to": {
                                                                    "type": "string"
                                                                },
                                                                "messages_considered": {
                                                                    "type": "integer"
                                                                },
                                                                "cached": {
                                                                    "type": "boolean"
                                                                }
                                                            }
                                                        },
                                                        "attention": {
                                                            "type": "object",
                                                            "description": "Unanswered and unread mail worth a look."
                                                        },
                                                        "response_time": {
                                                            "type": "object",
                                                            "description": "How long replies take, both ways."
                                                        },
                                                        "rhythm": {
                                                            "type": "object",
                                                            "description": "Busiest hours and days, in the holder's time zone."
                                                        },
                                                        "relationships": {
                                                            "type": "object",
                                                            "description": "Top correspondents."
                                                        },
                                                        "hygiene": {
                                                            "type": "object",
                                                            "description": "Newsletters and clutter."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Insights retrieved successfully",
                                    "data": {
                                        "window": {
                                            "from": "2026-07-13T00:00:00+00:00",
                                            "to": "2026-10-11T12:00:00+00:00",
                                            "messages_considered": 1696,
                                            "cached": true
                                        },
                                        "relationships": {
                                            "top_correspondents": [
                                                {
                                                    "email": "tunde@example.com",
                                                    "name": "Tunde Bello",
                                                    "messages": 64
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Insights are busy on this server; try again shortly.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/messages/{message_id}/context": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Who this message is with, and the shape of its conversation",
                "description": "Header-only context for one message: the history with its correspondent and the thread it belongs to. Always available \u2014 no AI is involved and none is required. A message with no identifiable correspondent (a bounce, a self-note) omits the correspondent block.",
                "operationId": "message_context_api_v1_mailbox_messages__message_id__context_get",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The history with this message\u2019s correspondent, and the shape of its thread.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "required": [
                                                        "message_id"
                                                    ],
                                                    "description": "Context for the message. `correspondent` is left out for a message with no other person (a bounce, a note to yourself) or a first message from that address; `thread` is left out when no message in the conversation has a usable date.",
                                                    "properties": {
                                                        "message_id": {
                                                            "type": "string",
                                                            "description": "The message this context is for, as `Folder:UID` \u2014 echoed back so a late response can be matched to the message still on screen. Example: `INBOX:4821`."
                                                        },
                                                        "correspondent": {
                                                            "type": "object",
                                                            "description": "Your history with the other party, counted across INBOX and Sent only. Archived or filed mail is not searched, so these are floors, not totals.",
                                                            "properties": {
                                                                "email": {
                                                                    "type": "string",
                                                                    "format": "email",
                                                                    "description": "The other party, lower-cased. On a message you sent this is the recipient, not you."
                                                                },
                                                                "messages_exchanged": {
                                                                    "type": "integer",
                                                                    "description": "Messages from them plus messages to them, in both directions and over all time. 1 means this is the only one."
                                                                },
                                                                "first_contact": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "description": "ISO 8601 with offset. The oldest message either way."
                                                                },
                                                                "last_contact": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "description": "ISO 8601 with offset. The newest message either way, which is usually the one you are looking at."
                                                                },
                                                                "you_replied_to_last": {
                                                                    "type": "boolean",
                                                                    "nullable": true,
                                                                    "description": "Whether you answered their latest message. Null when they have never written to you."
                                                                },
                                                                "unanswered_from_them": {
                                                                    "type": "integer",
                                                                    "description": "How many of their messages you have never replied to. Matched by In-Reply-To/References, never by subject."
                                                                },
                                                                "median_reply_minutes": {
                                                                    "type": "integer",
                                                                    "nullable": true,
                                                                    "description": "Your median turnaround to this person, in whole minutes. null when you have never replied to them \u2014 there is no median of nothing, and 0 would read as \"instantly\"."
                                                                }
                                                            }
                                                        },
                                                        "thread": {
                                                            "type": "object",
                                                            "description": "The conversation this message sits in, threaded on Message-ID/In-Reply-To/References and deduplicated, so a message you sent is counted once and not twice for its copy in Sent.",
                                                            "properties": {
                                                                "messages": {
                                                                    "type": "integer",
                                                                    "description": "Distinct messages in the thread, including this one. Always at least 1."
                                                                },
                                                                "spans_days": {
                                                                    "type": "integer",
                                                                    "description": "Whole days from the oldest message to the newest. 0 for a conversation that happened within one day."
                                                                },
                                                                "your_last_reply": {
                                                                    "type": "string",
                                                                    "format": "date-time",
                                                                    "nullable": true,
                                                                    "description": "When you last wrote in this thread, ISO 8601 with offset. null if you have not."
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Context retrieved successfully",
                                    "data": {
                                        "message_id": "INBOX:4821",
                                        "correspondent": {
                                            "email": "ada@example.com",
                                            "messages_exchanged": 37,
                                            "first_contact": "2025-02-11T09:14:00+00:00",
                                            "last_contact": "2026-09-18T07:41:00+00:00",
                                            "you_replied_to_last": false,
                                            "unanswered_from_them": 2,
                                            "median_reply_minutes": 94
                                        },
                                        "thread": {
                                            "messages": 6,
                                            "spans_days": 12,
                                            "your_last_reply": "2026-09-14T16:02:00+00:00"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/terms": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read the AI terms",
                "description": "The current AI assistant terms the holder is asked to accept, and their version.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "ai_terms_api_v1_mailbox_ai_terms_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "version": {
                                                            "type": "string"
                                                        },
                                                        "text": {
                                                            "type": "string"
                                                        },
                                                        "sha256": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "AI terms",
                                    "data": {
                                        "version": "2026-09",
                                        "text": "The assistant reads only the message you ask it about...",
                                        "sha256": "4f2a..."
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/consent": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read the AI consent",
                "description": "Current opt-in flags, the version accepted, when, the version currently in force, and the URL of the consent document. Deliberately available regardless of entitlement or org policy \u2014 reading one's own consent state is never gated.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "ai_consent_show_api_v1_mailbox_ai_consent_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "ai_assistant_opt_in": {
                                                            "type": "boolean"
                                                        },
                                                        "ai_training_opt_in": {
                                                            "type": "boolean"
                                                        },
                                                        "ai_terms_version": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "ai_assistant_opted_in_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "current_terms_version": {
                                                            "type": "string"
                                                        },
                                                        "document_url": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "A signed record of the decision."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "AI consent state",
                                    "data": {
                                        "ai_assistant_opt_in": true,
                                        "ai_training_opt_in": false,
                                        "ai_terms_version": "2026-09",
                                        "ai_assistant_opted_in_at": "2026-10-02T08:30:00+00:00",
                                        "current_terms_version": "2026-09",
                                        "document_url": "/api/v1/mailbox/ai/consent/01JABC/document"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Accept the AI terms",
                "description": "Records the holder's acceptance of the current terms (`terms_version` from `GET /ai/terms`). `accept_training` is a separate, optional choice.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `409` | The terms changed since they were read; show the current ones. |\n| `422` | `accept_assistant` must be true (withdraw with `DELETE /ai/consent`). |",
                "operationId": "ai_consent_accept_api_v1_mailbox_ai_consent_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "accept_assistant": {
                                        "type": "boolean",
                                        "title": "Accept Assistant",
                                        "description": "Must be true: accepting the assistant terms."
                                    },
                                    "accept_training": {
                                        "type": "boolean",
                                        "title": "Accept Training",
                                        "default": false,
                                        "description": "Also allow use for improving the assistant. Optional, separate."
                                    },
                                    "terms_version": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "minLength": 1,
                                        "title": "Terms Version",
                                        "description": "The `version` from `GET /ai/terms` that the holder read."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "accept_assistant",
                                    "terms_version"
                                ],
                                "title": "ConsentRequest"
                            },
                            "example": {
                                "accept_assistant": true,
                                "accept_training": false,
                                "terms_version": "2026-09"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "document_url": {
                                                            "type": "string"
                                                        },
                                                        "consent_id": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Consent recorded",
                                    "data": {
                                        "document_url": "/api/v1/mailbox/ai/consent/01JABC/document",
                                        "consent_id": "01JABC"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`accept_assistant` must be true (withdraw with `DELETE /ai/consent`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The terms changed since they were read; show the current ones.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Withdraw AI consent",
                "description": "Withdraws both the assistant and training decisions and writes a 'revoked' ledger entry with its own receipt document. Idempotent: with nothing to withdraw it succeeds without writing anything.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "ai_consent_withdraw_api_v1_mailbox_ai_consent_delete",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "document_url": {
                                                            "type": "string"
                                                        },
                                                        "consent_id": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Consent withdrawn",
                                    "data": {
                                        "document_url": "/api/v1/mailbox/ai/consent/01JABD/document",
                                        "consent_id": "01JABD"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/consent/training": {
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Withdraw the training choice only",
                "description": "Turns off use of this mailbox's requests for model improvement while leaving the assistant itself consented. Idempotent.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "ai_consent_withdraw_training_api_v1_mailbox_ai_consent_training_delete",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "document_url": {
                                                            "type": "string"
                                                        },
                                                        "consent_id": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Training consent withdrawn",
                                    "data": {
                                        "document_url": "/api/v1/mailbox/ai/consent/01JABE/document",
                                        "consent_id": "01JABE"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/consent/history": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "AI consent history",
                "description": "Every consent decision, newest first.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "ai_consent_history_api_v1_mailbox_ai_consent_history_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string"
                                                            },
                                                            "action": {
                                                                "type": "string",
                                                                "description": "What was decided, e.g. accepted or withdrawn."
                                                            },
                                                            "actor": {
                                                                "type": "string"
                                                            },
                                                            "at": {
                                                                "type": "string"
                                                            },
                                                            "terms_version": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "included_training": {
                                                                "type": "boolean"
                                                            },
                                                            "document_url": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Consent history",
                                    "data": [
                                        {
                                            "id": "01JABC",
                                            "action": "accepted",
                                            "actor": "ada@yourdomain.com",
                                            "at": "2026-10-02T08:30:00+00:00",
                                            "terms_version": "2026-09",
                                            "included_training": false,
                                            "document_url": "/api/v1/mailbox/ai/consent/01JABC/document"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/consent/{consent_id}/document": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Download a consent record",
                "description": "The signed record of one decision, as a file.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Document not found. |",
                "operationId": "ai_consent_document_api_v1_mailbox_ai_consent__consent_id__document_get",
                "parameters": [
                    {
                        "name": "consent_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Consent Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The document.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Document not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/summarize/thread/{message_id}": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Summarise a conversation with AI",
                "description": "No body. Only when `capabilities.ai` is true and the holder has accepted the AI terms (`POST /ai/consent`).\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Message not found. |\n| `422` | The conversation has no text to summarise. |",
                "operationId": "ai_summarize_thread_api_v1_mailbox_ai_summarize_thread__message_id__post",
                "parameters": [
                    {
                        "name": "message_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Message Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "summary": {
                                                            "type": "string"
                                                        },
                                                        "message_count": {
                                                            "type": "integer"
                                                        },
                                                        "ai_calls_remaining": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Thread summary generated",
                                    "data": {
                                        "summary": "Ada and Tunde agreed the Q3 figures; Q4 forecast due Friday.",
                                        "message_count": 6,
                                        "ai_calls_remaining": 45
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The conversation has no text to summarise.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Message not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/ai/classify": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Sort emails into categories with AI",
                "description": "Labels a batch of messages as primary, newsletter, promotion, social, notification, finance, travel, action_required or other. Only when `capabilities.ai` is true and the holder has accepted the AI terms (`POST /ai/consent`).\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `502` | The AI service did not answer usefully. |",
                "operationId": "ai_classify_api_v1_mailbox_ai_classify_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "items": {
                                        "items": {
                                            "$ref": "#/components/schemas/ClassifyItem"
                                        },
                                        "type": "array",
                                        "maxItems": 20,
                                        "minItems": 1,
                                        "title": "Items",
                                        "description": "The messages to sort: each an `id`, its `subject` and a `preview`."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "items"
                                ],
                                "title": "ClassifyRequest"
                            },
                            "example": {
                                "items": [
                                    {
                                        "id": "INBOX:4821",
                                        "subject": "Your invoice for October",
                                        "preview": "Amount due: \u20a684,000"
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "items": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string"
                                                                    },
                                                                    "label": {
                                                                        "type": "string"
                                                                    },
                                                                    "confidence": {
                                                                        "type": "number"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "labels": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "ai_calls_remaining": {
                                                            "type": "integer"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Messages classified",
                                    "data": {
                                        "items": [
                                            {
                                                "id": "INBOX:4821",
                                                "label": "finance",
                                                "confidence": 0.93
                                            }
                                        ],
                                        "labels": [
                                            "primary",
                                            "newsletter",
                                            "promotion",
                                            "social",
                                            "notification",
                                            "finance",
                                            "travel",
                                            "action_required",
                                            "other"
                                        ],
                                        "ai_calls_remaining": 44
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "The AI service did not answer usefully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/devices": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Register a device for push",
                "description": "From a phone app, after sign-in: the push token from APNs or FCM. New mail then raises a notification on this device. Registering the same token again just updates it.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "register_device_api_v1_mailbox_devices_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "token": {
                                        "type": "string",
                                        "maxLength": 512,
                                        "minLength": 1,
                                        "title": "Token",
                                        "description": "The device's push token from APNs or FCM."
                                    },
                                    "platform": {
                                        "type": "string",
                                        "maxLength": 16,
                                        "title": "Platform",
                                        "description": "`ios` or `android`."
                                    },
                                    "app_version": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 32
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "App Version",
                                        "description": "Your app's version, for support."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "token",
                                    "platform"
                                ],
                                "title": "DeviceRegistration"
                            },
                            "example": {
                                "token": "fcm-or-apns-device-token",
                                "platform": "ios",
                                "app_version": "2.1.0"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "platform": {
                                                            "type": "string"
                                                        },
                                                        "app_version": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "created_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "last_seen_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "push_enabled": {
                                                            "type": "boolean"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Device registered",
                                    "data": {
                                        "id": "01J9ZR...",
                                        "platform": "ios",
                                        "app_version": "2.1.0",
                                        "created_at": "2026-10-11T08:00:00+00:00",
                                        "last_seen_at": "2026-10-11T08:00:00+00:00",
                                        "push_enabled": true
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Unknown platform, or token too long",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Database unavailable",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/devices/current": {
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Stop push to this device",
                "description": "Unregisters the device this session belongs to. Call it on sign-out in your app.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "unregister_current_device_api_v1_mailbox_devices_current_delete",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "platform": {
                                                            "type": "string"
                                                        },
                                                        "app_version": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "created_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "last_seen_at": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "push_enabled": {
                                                            "type": "boolean"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Device unregistered",
                                    "data": {
                                        "id": "",
                                        "platform": "",
                                        "app_version": null,
                                        "created_at": null,
                                        "last_seen_at": null,
                                        "push_enabled": false
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Database unavailable",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendars": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List calendars",
                "operationId": "list_calendars_api_v1_mailbox_calendars_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "uri": {
                                                                "type": "string",
                                                                "description": "Use as `{calendar}` in event URLs."
                                                            },
                                                            "name": {
                                                                "type": "string"
                                                            },
                                                            "color": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "description": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "read_only": {
                                                                "type": "boolean"
                                                            },
                                                            "is_default": {
                                                                "type": "boolean"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Calendars retrieved successfully",
                                    "data": [
                                        {
                                            "uri": "default",
                                            "name": "Calendar",
                                            "color": "#4f46e5",
                                            "description": null,
                                            "read_only": false,
                                            "is_default": true
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendars/{calendar}/events": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List events in a time range",
                "operationId": "list_events_api_v1_mailbox_calendars__calendar__events_get",
                "parameters": [
                    {
                        "name": "calendar",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Calendar"
                        }
                    },
                    {
                        "name": "start",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "date-time",
                            "description": "ISO 8601, inclusive",
                            "title": "Start"
                        },
                        "description": "ISO 8601, inclusive"
                    },
                    {
                        "name": "end",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "date-time",
                            "description": "ISO 8601, exclusive",
                            "title": "End"
                        },
                        "description": "ISO 8601, exclusive"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string",
                                                                "description": "The event's id within its calendar; use it in the event URLs."
                                                            },
                                                            "etag": {
                                                                "type": "string",
                                                                "description": "Send it back as `etag` when you update or delete, so a change made elsewhere is not overwritten."
                                                            },
                                                            "calendar": {
                                                                "type": "string"
                                                            },
                                                            "uid": {
                                                                "type": "string"
                                                            },
                                                            "summary": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "description": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "location": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "status": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "start": {
                                                                "type": "string",
                                                                "description": "ISO 8601."
                                                            },
                                                            "end": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "timezone": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "all_day": {
                                                                "type": "boolean"
                                                            },
                                                            "recurring": {
                                                                "type": "boolean"
                                                            },
                                                            "rrule": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "sequence": {
                                                                "type": "integer"
                                                            },
                                                            "organizer": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "email": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            },
                                                            "attendees": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "email": {
                                                                            "type": "string"
                                                                        },
                                                                        "name": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        },
                                                                        "status": {
                                                                            "type": "string"
                                                                        },
                                                                        "role": {
                                                                            "type": "string"
                                                                        },
                                                                        "rsvp": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "schedule_status": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "alarms": {
                                                                "type": "integer"
                                                            },
                                                            "reminders": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "integer"
                                                                },
                                                                "description": "Minutes before the start."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Events retrieved successfully",
                                    "data": [
                                        {
                                            "id": "8f14e45f.ics",
                                            "etag": "\"a1b2c3\"",
                                            "calendar": "default",
                                            "uid": "8f14e45f@yourdomain.com",
                                            "summary": "Quarterly review",
                                            "description": "Q3 numbers and the plan for Q4.",
                                            "location": "Board room",
                                            "status": "CONFIRMED",
                                            "start": "2026-10-14T10:00:00+01:00",
                                            "end": "2026-10-14T11:00:00+01:00",
                                            "timezone": "Africa/Lagos",
                                            "all_day": false,
                                            "recurring": false,
                                            "rrule": null,
                                            "sequence": 0,
                                            "organizer": {
                                                "email": "ada@yourdomain.com",
                                                "name": "Ada Obi"
                                            },
                                            "attendees": [
                                                {
                                                    "email": "tunde@example.com",
                                                    "name": "Tunde Bello",
                                                    "status": "NEEDS-ACTION",
                                                    "role": "REQ-PARTICIPANT",
                                                    "rsvp": true,
                                                    "schedule_status": null
                                                }
                                            ],
                                            "alarms": 1,
                                            "reminders": [
                                                15
                                            ]
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`end must be after start`, a range over 400 days, or an invalid time zone.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No calendar by that name.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Events overlapping `start`\u2013`end` (ISO 8601, at most 400 days apart). Repeating events come back once per occurrence in the range.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | `end must be after start`, a range over 400 days, or an invalid time zone. |\n| `404` | No calendar by that name. |"
            },
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Create an event",
                "operationId": "create_event_api_v1_mailbox_calendars__calendar__events_post",
                "parameters": [
                    {
                        "name": "calendar",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Calendar"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "summary": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "minLength": 1,
                                        "title": "Summary",
                                        "description": "The event's title."
                                    },
                                    "start": {
                                        "type": "string",
                                        "format": "date-time",
                                        "title": "Start",
                                        "description": "ISO 8601."
                                    },
                                    "end": {
                                        "type": "string",
                                        "format": "date-time",
                                        "title": "End",
                                        "description": "ISO 8601, after `start`."
                                    },
                                    "timezone_id": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 64
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Timezone Id",
                                        "description": "An IANA time zone, e.g. `Africa/Lagos`."
                                    },
                                    "all_day": {
                                        "type": "boolean",
                                        "title": "All Day",
                                        "default": false,
                                        "description": "A whole-day event (dates only)."
                                    },
                                    "description": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 20000
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Description",
                                        "description": "Notes."
                                    },
                                    "location": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 500
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Location",
                                        "description": "Where."
                                    },
                                    "rrule": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 500
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Rrule",
                                        "description": "Repeat rule (RFC 5545), e.g. `FREQ=WEEKLY;BYDAY=MO`."
                                    },
                                    "reminder_minutes": {
                                        "anyOf": [
                                            {
                                                "type": "integer",
                                                "maximum": 40320,
                                                "minimum": 0
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Reminder Minutes",
                                        "description": "One reminder, minutes before."
                                    },
                                    "reminders": {
                                        "anyOf": [
                                            {
                                                "items": {
                                                    "type": "integer",
                                                    "maximum": 40320,
                                                    "minimum": 0
                                                },
                                                "type": "array",
                                                "maxItems": 10
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Reminders",
                                        "description": "Several reminders, minutes before each."
                                    },
                                    "attendees": {
                                        "anyOf": [
                                            {
                                                "items": {
                                                    "additionalProperties": true,
                                                    "type": "object"
                                                },
                                                "type": "array"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Attendees",
                                        "description": "People to invite: `email` and optional `name`. They are emailed an invitation."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "summary",
                                    "start",
                                    "end"
                                ],
                                "title": "EventInput"
                            },
                            "example": {
                                "summary": "Quarterly review",
                                "start": "2026-10-14T10:00:00+01:00",
                                "end": "2026-10-14T11:00:00+01:00",
                                "timezone_id": "Africa/Lagos",
                                "location": "Board room",
                                "reminders": [
                                    15
                                ],
                                "attendees": [
                                    {
                                        "email": "tunde@example.com",
                                        "name": "Tunde Bello"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": []
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "etag": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Event created successfully",
                                    "data": {
                                        "id": "8f14e45f.ics",
                                        "etag": "\"a1b2c3\""
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Creates an event. Attendees are emailed an invitation.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendars/{calendar}/events/{event_id}": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read an event",
                "operationId": "get_event_api_v1_mailbox_calendars__calendar__events__event_id__get",
                "parameters": [
                    {
                        "name": "calendar",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Calendar"
                        }
                    },
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Event Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string",
                                                            "description": "The event's id within its calendar; use it in the event URLs."
                                                        },
                                                        "etag": {
                                                            "type": "string",
                                                            "description": "Send it back as `etag` when you update or delete, so a change made elsewhere is not overwritten."
                                                        },
                                                        "calendar": {
                                                            "type": "string"
                                                        },
                                                        "uid": {
                                                            "type": "string"
                                                        },
                                                        "summary": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "description": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "location": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "status": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "start": {
                                                            "type": "string",
                                                            "description": "ISO 8601."
                                                        },
                                                        "end": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "timezone": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "all_day": {
                                                            "type": "boolean"
                                                        },
                                                        "recurring": {
                                                            "type": "boolean"
                                                        },
                                                        "rrule": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "sequence": {
                                                            "type": "integer"
                                                        },
                                                        "organizer": {
                                                            "type": "object",
                                                            "properties": {
                                                                "email": {
                                                                    "type": "string"
                                                                },
                                                                "name": {
                                                                    "type": [
                                                                        "string",
                                                                        "null"
                                                                    ]
                                                                }
                                                            }
                                                        },
                                                        "attendees": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "email": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    },
                                                                    "status": {
                                                                        "type": "string"
                                                                    },
                                                                    "role": {
                                                                        "type": "string"
                                                                    },
                                                                    "rsvp": {
                                                                        "type": "boolean"
                                                                    },
                                                                    "schedule_status": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "alarms": {
                                                            "type": "integer"
                                                        },
                                                        "reminders": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "integer"
                                                            },
                                                            "description": "Minutes before the start."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Event retrieved successfully",
                                    "data": {
                                        "id": "8f14e45f.ics",
                                        "etag": "\"a1b2c3\"",
                                        "calendar": "default",
                                        "uid": "8f14e45f@yourdomain.com",
                                        "summary": "Quarterly review",
                                        "description": "Q3 numbers and the plan for Q4.",
                                        "location": "Board room",
                                        "status": "CONFIRMED",
                                        "start": "2026-10-14T10:00:00+01:00",
                                        "end": "2026-10-14T11:00:00+01:00",
                                        "timezone": "Africa/Lagos",
                                        "all_day": false,
                                        "recurring": false,
                                        "rrule": null,
                                        "sequence": 0,
                                        "organizer": {
                                            "email": "ada@yourdomain.com",
                                            "name": "Ada Obi"
                                        },
                                        "attendees": [
                                            {
                                                "email": "tunde@example.com",
                                                "name": "Tunde Bello",
                                                "status": "NEEDS-ACTION",
                                                "role": "REQ-PARTICIPANT",
                                                "rsvp": true,
                                                "schedule_status": null
                                            }
                                        ],
                                        "alarms": 1,
                                        "reminders": [
                                            15
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Event not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Event not found. |"
            },
            "put": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Update an event",
                "operationId": "update_event_api_v1_mailbox_calendars__calendar__events__event_id__put",
                "parameters": [
                    {
                        "name": "calendar",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Calendar"
                        }
                    },
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Event Id"
                        }
                    },
                    {
                        "name": "etag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Etag"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "summary": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "minLength": 1,
                                        "title": "Summary",
                                        "description": "The event's title."
                                    },
                                    "start": {
                                        "type": "string",
                                        "format": "date-time",
                                        "title": "Start",
                                        "description": "ISO 8601."
                                    },
                                    "end": {
                                        "type": "string",
                                        "format": "date-time",
                                        "title": "End",
                                        "description": "ISO 8601, after `start`."
                                    },
                                    "timezone_id": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 64
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Timezone Id",
                                        "description": "An IANA time zone, e.g. `Africa/Lagos`."
                                    },
                                    "all_day": {
                                        "type": "boolean",
                                        "title": "All Day",
                                        "default": false,
                                        "description": "A whole-day event (dates only)."
                                    },
                                    "description": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 20000
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Description",
                                        "description": "Notes."
                                    },
                                    "location": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 500
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Location",
                                        "description": "Where."
                                    },
                                    "rrule": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 500
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Rrule",
                                        "description": "Repeat rule (RFC 5545), e.g. `FREQ=WEEKLY;BYDAY=MO`."
                                    },
                                    "reminder_minutes": {
                                        "anyOf": [
                                            {
                                                "type": "integer",
                                                "maximum": 40320,
                                                "minimum": 0
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Reminder Minutes",
                                        "description": "One reminder, minutes before."
                                    },
                                    "reminders": {
                                        "anyOf": [
                                            {
                                                "items": {
                                                    "type": "integer",
                                                    "maximum": 40320,
                                                    "minimum": 0
                                                },
                                                "type": "array",
                                                "maxItems": 10
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Reminders",
                                        "description": "Several reminders, minutes before each."
                                    },
                                    "attendees": {
                                        "anyOf": [
                                            {
                                                "items": {
                                                    "additionalProperties": true,
                                                    "type": "object"
                                                },
                                                "type": "array"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Attendees",
                                        "description": "People to invite: `email` and optional `name`. They are emailed an invitation."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "summary",
                                    "start",
                                    "end"
                                ],
                                "title": "EventInput"
                            },
                            "example": {
                                "summary": "Quarterly review",
                                "start": "2026-10-14T10:00:00+01:00",
                                "end": "2026-10-14T11:00:00+01:00",
                                "timezone_id": "Africa/Lagos",
                                "location": "Board room",
                                "reminders": [
                                    15
                                ],
                                "attendees": [
                                    {
                                        "email": "tunde@example.com",
                                        "name": "Tunde Bello"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "etag": {
                                                            "type": "string",
                                                            "description": "The new etag."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Event updated successfully",
                                    "data": {
                                        "id": "8f14e45f.ics",
                                        "etag": "\"d4e5f6\""
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Event not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "`This event changed elsewhere. Reload and try again.`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Replaces the event. Send the `etag` you read (as a query parameter) so a change made elsewhere is not overwritten. Attendees are told of the change.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Event not found. |\n| `409` | `This event changed elsewhere. Reload and try again.` |"
            },
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Delete an event",
                "operationId": "delete_event_api_v1_mailbox_calendars__calendar__events__event_id__delete",
                "parameters": [
                    {
                        "name": "calendar",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Calendar"
                        }
                    },
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Event Id"
                        }
                    },
                    {
                        "name": "etag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Etag"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Event deleted successfully"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Deletes the event; attendees are told it was cancelled. Pass `etag` to delete only the version you read.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendar-subscriptions": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List calendar subscription links",
                "operationId": "list_subscriptions_api_v1_mailbox_calendar_subscriptions_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "token": {
                                                                "type": "string"
                                                            },
                                                            "calendar_uri": {
                                                                "type": "string"
                                                            },
                                                            "label": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "url": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "webcal_url": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "created_at": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "last_accessed_at": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Subscriptions retrieved successfully",
                                    "data": [
                                        {
                                            "token": "s3cr3t-token",
                                            "calendar_uri": "default",
                                            "label": "My phone",
                                            "url": "https://mail.mailyte.com/ics/s3cr3t-token.ics",
                                            "webcal_url": "webcal://mail.mailyte.com/ics/s3cr3t-token.ics",
                                            "created_at": "2026-10-01T10:00:00+00:00",
                                            "last_accessed_at": "2026-10-11T07:00:00+00:00"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Private links that let another calendar app (Google, Outlook, Apple) show this calendar, read-only.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Create a subscription link",
                "operationId": "create_subscription_api_v1_mailbox_calendar_subscriptions_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "calendar": {
                                        "type": "string",
                                        "maxLength": 200,
                                        "title": "Calendar",
                                        "default": "default",
                                        "description": "Which calendar the link shows (default `default`)."
                                    },
                                    "label": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 100
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Label",
                                        "description": "A name to tell links apart."
                                    }
                                },
                                "type": "object",
                                "title": "SubscriptionInput"
                            },
                            "example": {
                                "calendar": "default",
                                "label": "My phone"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": []
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "token": {
                                                            "type": "string"
                                                        },
                                                        "calendar_uri": {
                                                            "type": "string"
                                                        },
                                                        "label": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "url": {
                                                            "type": "string"
                                                        },
                                                        "webcal_url": {
                                                            "type": "string"
                                                        },
                                                        "created_at": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Subscription link created",
                                    "data": {
                                        "token": "s3cr3t-token",
                                        "calendar_uri": "default",
                                        "label": "My phone",
                                        "url": "https://mail.mailyte.com/ics/s3cr3t-token.ics",
                                        "webcal_url": "webcal://mail.mailyte.com/ics/s3cr3t-token.ics",
                                        "created_at": "2026-10-11T12:00:00+00:00"
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendar-subscriptions/{token}": {
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Revoke a subscription link",
                "operationId": "revoke_subscription_api_v1_mailbox_calendar_subscriptions__token__delete",
                "parameters": [
                    {
                        "name": "token",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Token"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Subscription link revoked"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Subscription link not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "The link stops working at once.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Subscription link not found. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendar/rooms": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List rooms and equipment",
                "description": "Rooms (`ROOM`) and things (`RESOURCE`, e.g. a projector) you can add to an event like an attendee. Empty for most organizations.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "list_rooms_api_v1_mailbox_calendar_rooms_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "email": {
                                                                "type": "string"
                                                            },
                                                            "name": {
                                                                "type": "string"
                                                            },
                                                            "type": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "ROOM",
                                                                    "RESOURCE"
                                                                ]
                                                            },
                                                            "capacity": {
                                                                "type": [
                                                                    "integer",
                                                                    "null"
                                                                ]
                                                            },
                                                            "location": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Rooms retrieved successfully",
                                    "data": [
                                        {
                                            "email": "boardroom@yourdomain.com",
                                            "name": "Board room",
                                            "type": "ROOM",
                                            "capacity": 12,
                                            "location": "3rd floor"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendar/free-busy": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Check when people are busy",
                "description": "Busy periods for colleagues in `start`\u2013`end` (at most 31 days). `known: false` means the server cannot see that person's calendar (usually someone outside the organization): treat it as unknown, never as free.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | `end must be after start`, a range over 31 days, or `No valid addresses`. |",
                "operationId": "free_busy_api_v1_mailbox_calendar_free_busy_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "attendees": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array",
                                        "maxItems": 25,
                                        "minItems": 1,
                                        "title": "Attendees",
                                        "description": "Addresses to check."
                                    },
                                    "start": {
                                        "type": "string",
                                        "format": "date-time",
                                        "title": "Start",
                                        "description": "ISO 8601."
                                    },
                                    "end": {
                                        "type": "string",
                                        "format": "date-time",
                                        "title": "End",
                                        "description": "ISO 8601, at most 31 days after `start`."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "attendees",
                                    "start",
                                    "end"
                                ],
                                "title": "FreeBusyInput"
                            },
                            "example": {
                                "attendees": [
                                    "tunde@yourdomain.com"
                                ],
                                "start": "2026-10-14T08:00:00+01:00",
                                "end": "2026-10-14T18:00:00+01:00"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "email": {
                                                                "type": "string"
                                                            },
                                                            "known": {
                                                                "type": "boolean"
                                                            },
                                                            "busy": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "start": {
                                                                            "type": "string"
                                                                        },
                                                                        "end": {
                                                                            "type": "string"
                                                                        }
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Availability retrieved successfully",
                                    "data": [
                                        {
                                            "email": "tunde@yourdomain.com",
                                            "known": true,
                                            "busy": [
                                                {
                                                    "start": "2026-10-14T10:00:00+01:00",
                                                    "end": "2026-10-14T11:00:00+01:00"
                                                }
                                            ]
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`end must be after start`, a range over 31 days, or `No valid addresses`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendar/invitations": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List invitations to answer",
                "description": "Invitations other people sent that still need an answer.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "list_invitations_api_v1_mailbox_calendar_invitations_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string",
                                                                "description": "The event's id within its calendar; use it in the event URLs."
                                                            },
                                                            "etag": {
                                                                "type": "string",
                                                                "description": "Send it back as `etag` when you update or delete, so a change made elsewhere is not overwritten."
                                                            },
                                                            "calendar": {
                                                                "type": "string"
                                                            },
                                                            "uid": {
                                                                "type": "string"
                                                            },
                                                            "summary": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "description": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "location": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "status": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "start": {
                                                                "type": "string",
                                                                "description": "ISO 8601."
                                                            },
                                                            "end": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "timezone": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "all_day": {
                                                                "type": "boolean"
                                                            },
                                                            "recurring": {
                                                                "type": "boolean"
                                                            },
                                                            "rrule": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "sequence": {
                                                                "type": "integer"
                                                            },
                                                            "organizer": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "email": {
                                                                        "type": "string"
                                                                    },
                                                                    "name": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            },
                                                            "attendees": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "email": {
                                                                            "type": "string"
                                                                        },
                                                                        "name": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        },
                                                                        "status": {
                                                                            "type": "string"
                                                                        },
                                                                        "role": {
                                                                            "type": "string"
                                                                        },
                                                                        "rsvp": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "schedule_status": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "alarms": {
                                                                "type": "integer"
                                                            },
                                                            "reminders": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "integer"
                                                                },
                                                                "description": "Minutes before the start."
                                                            },
                                                            "method": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "description": "REQUEST, CANCEL or REPLY."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Invitations retrieved successfully",
                                    "data": [
                                        {
                                            "id": "8f14e45f.ics",
                                            "etag": "\"a1b2c3\"",
                                            "calendar": "default",
                                            "uid": "8f14e45f@yourdomain.com",
                                            "summary": "Quarterly review",
                                            "description": "Q3 numbers and the plan for Q4.",
                                            "location": "Board room",
                                            "status": "CONFIRMED",
                                            "start": "2026-10-14T10:00:00+01:00",
                                            "end": "2026-10-14T11:00:00+01:00",
                                            "timezone": "Africa/Lagos",
                                            "all_day": false,
                                            "recurring": false,
                                            "rrule": null,
                                            "sequence": 0,
                                            "organizer": {
                                                "email": "tunde@example.com",
                                                "name": "Tunde Bello"
                                            },
                                            "attendees": [
                                                {
                                                    "email": "tunde@example.com",
                                                    "name": "Tunde Bello",
                                                    "status": "NEEDS-ACTION",
                                                    "role": "REQ-PARTICIPANT",
                                                    "rsvp": true,
                                                    "schedule_status": null
                                                }
                                            ],
                                            "alarms": 1,
                                            "reminders": [
                                                15
                                            ],
                                            "method": "REQUEST"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/calendar/invitations/{invitation_id}/rsvp": {
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Answer an invitation",
                "description": "Accepts, declines or tentatively accepts. The organizer is emailed the answer and, unless declined, the event goes in `calendar`.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | `That invitation is no longer there`. |\n| `422` | `response` is not accepted, declined or tentative, or the invitation cannot be read. |",
                "operationId": "rsvp_api_v1_mailbox_calendar_invitations__invitation_id__rsvp_post",
                "parameters": [
                    {
                        "name": "invitation_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Invitation Id"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "response": {
                                        "type": "string",
                                        "pattern": "^(accepted|declined|tentative)$",
                                        "title": "Response",
                                        "description": "`accepted`, `declined` or `tentative`."
                                    },
                                    "calendar": {
                                        "type": "string",
                                        "maxLength": 200,
                                        "title": "Calendar",
                                        "default": "default",
                                        "description": "Where to put the event (default `default`)."
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "response"
                                ],
                                "title": "RsvpInput"
                            },
                            "example": {
                                "response": "accepted",
                                "calendar": "default"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "response": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Your answer has been sent",
                                    "data": {
                                        "id": "8f14e45f.ics",
                                        "response": "accepted"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`response` is not accepted, declined or tentative, or the invitation cannot be read.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "`That invitation is no longer there`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/address-book/books": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List address books",
                "description": "The personal collection, plus anything shared with the mailbox.\n\n`read_only` is reported off the server's own privilege set rather than\nguessed from the name, so a UI can hide editing controls on a collection\nthe server would refuse to write anyway \u2014 the company directory being the\ncase that matters.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |",
                "operationId": "list_books_api_v1_mailbox_address_book_books_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "uri": {
                                                                "type": "string",
                                                                "description": "Use as `book` in the contact calls."
                                                            },
                                                            "name": {
                                                                "type": "string"
                                                            },
                                                            "description": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "read_only": {
                                                                "type": "boolean"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Address books retrieved successfully",
                                    "data": [
                                        {
                                            "uri": "default",
                                            "name": "Contacts",
                                            "description": null,
                                            "read_only": false
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/address-book/contacts": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "List saved contacts",
                "operationId": "list_contacts_api_v1_mailbox_address_book_contacts_get",
                "parameters": [
                    {
                        "name": "book",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "default": "default",
                            "title": "Book"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "id": {
                                                                "type": "string"
                                                            },
                                                            "etag": {
                                                                "type": "string"
                                                            },
                                                            "book": {
                                                                "type": "string"
                                                            },
                                                            "read_only": {
                                                                "type": "boolean"
                                                            },
                                                            "uid": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "full_name": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "first_name": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "last_name": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "emails": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "address": {
                                                                            "type": "string"
                                                                        },
                                                                        "type": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "phones": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "number": {
                                                                            "type": "string"
                                                                        },
                                                                        "type": {
                                                                            "type": [
                                                                                "string",
                                                                                "null"
                                                                            ]
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "organization": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "title": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "address": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "note": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ]
                                                            },
                                                            "birthday": {
                                                                "type": [
                                                                    "string",
                                                                    "null"
                                                                ],
                                                                "description": "YYYY-MM-DD."
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Contacts retrieved successfully",
                                    "data": [
                                        {
                                            "id": "5d41402a.vcf",
                                            "etag": "\"c0ffee\"",
                                            "book": "default",
                                            "read_only": false,
                                            "uid": "5d41402a",
                                            "full_name": "Tunde Bello",
                                            "first_name": "Tunde",
                                            "last_name": "Bello",
                                            "emails": [
                                                {
                                                    "address": "tunde@example.com",
                                                    "type": "work"
                                                }
                                            ],
                                            "phones": [
                                                {
                                                    "number": "+234 803 000 0000",
                                                    "type": "mobile"
                                                }
                                            ],
                                            "organization": "Example Ltd",
                                            "title": "CFO",
                                            "address": null,
                                            "note": null,
                                            "birthday": null
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Address book not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Contacts in one address book (`book`, default `default`).\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Address book not found. |"
            },
            "post": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Save a contact",
                "operationId": "create_contact_api_v1_mailbox_address_book_contacts_post",
                "parameters": [
                    {
                        "name": "book",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "default": "default",
                            "title": "Book"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "full_name": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 255
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Full Name",
                                        "description": "The name to show."
                                    },
                                    "first_name": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 100
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "First Name",
                                        "description": "Given name."
                                    },
                                    "last_name": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 100
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Last Name",
                                        "description": "Family name."
                                    },
                                    "emails": {
                                        "items": {
                                            "$ref": "#/components/schemas/EmailInput"
                                        },
                                        "type": "array",
                                        "maxItems": 10,
                                        "title": "Emails",
                                        "description": "Addresses: each an `address` and optional `type` (work, home)."
                                    },
                                    "phones": {
                                        "items": {
                                            "$ref": "#/components/schemas/PhoneInput"
                                        },
                                        "type": "array",
                                        "maxItems": 10,
                                        "title": "Phones",
                                        "description": "Numbers: each a `number` and optional `type`."
                                    },
                                    "organization": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 255
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Organization",
                                        "description": "Company."
                                    },
                                    "title": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 255
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Title",
                                        "description": "Job title."
                                    },
                                    "address": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 500
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Address",
                                        "description": "Postal address."
                                    },
                                    "note": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 2000
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Note",
                                        "description": "Notes."
                                    },
                                    "birthday": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 32
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Birthday",
                                        "description": "YYYY-MM-DD."
                                    }
                                },
                                "type": "object",
                                "title": "ContactInput",
                                "description": "The contact. Every field is optional; a contact can be just a phone number."
                            },
                            "example": {
                                "full_name": "Tunde Bello",
                                "emails": [
                                    {
                                        "address": "tunde@example.com",
                                        "type": "work"
                                    }
                                ],
                                "phones": [
                                    {
                                        "number": "+234 803 000 0000",
                                        "type": "mobile"
                                    }
                                ],
                                "organization": "Example Ltd"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": []
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`Give the contact a name, an address or a number`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "`That address book cannot be written to`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "etag": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Contact saved successfully",
                                    "data": {
                                        "id": "5d41402a.vcf",
                                        "etag": "\"c0ffee\""
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "Needs at least a name, an address or a number.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | `Give the contact a name, an address or a number`. |\n| `409` | `That address book cannot be written to`. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        },
        "/api/v1/mailbox/address-book/contacts/{card_id}": {
            "get": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Read a contact",
                "operationId": "get_contact_api_v1_mailbox_address_book_contacts__card_id__get",
                "parameters": [
                    {
                        "name": "card_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Card Id"
                        }
                    },
                    {
                        "name": "book",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "default": "default",
                            "title": "Book"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "etag": {
                                                            "type": "string"
                                                        },
                                                        "book": {
                                                            "type": "string"
                                                        },
                                                        "read_only": {
                                                            "type": "boolean"
                                                        },
                                                        "uid": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "full_name": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "first_name": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "last_name": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "emails": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "address": {
                                                                        "type": "string"
                                                                    },
                                                                    "type": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "phones": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "number": {
                                                                        "type": "string"
                                                                    },
                                                                    "type": {
                                                                        "type": [
                                                                            "string",
                                                                            "null"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "organization": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "title": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "address": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "note": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ]
                                                        },
                                                        "birthday": {
                                                            "type": [
                                                                "string",
                                                                "null"
                                                            ],
                                                            "description": "YYYY-MM-DD."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Contact retrieved successfully",
                                    "data": {
                                        "id": "5d41402a.vcf",
                                        "etag": "\"c0ffee\"",
                                        "book": "default",
                                        "read_only": false,
                                        "uid": "5d41402a",
                                        "full_name": "Tunde Bello",
                                        "first_name": "Tunde",
                                        "last_name": "Bello",
                                        "emails": [
                                            {
                                                "address": "tunde@example.com",
                                                "type": "work"
                                            }
                                        ],
                                        "phones": [
                                            {
                                                "number": "+234 803 000 0000",
                                                "type": "mobile"
                                            }
                                        ],
                                        "organization": "Example Ltd",
                                        "title": "CFO",
                                        "address": null,
                                        "note": null,
                                        "birthday": null
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Contact not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Contact not found. |"
            },
            "put": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Update a contact",
                "description": "Replaces the contact. Send the `etag` you read as a query parameter so a change made elsewhere is not lost.\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `400` | No name, address or number. |\n| `412` | `This contact changed elsewhere. Reopen it and try again.` |",
                "operationId": "update_contact_api_v1_mailbox_address_book_contacts__card_id__put",
                "parameters": [
                    {
                        "name": "card_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Card Id"
                        }
                    },
                    {
                        "name": "etag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Etag"
                        }
                    },
                    {
                        "name": "book",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "default": "default",
                            "title": "Book"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "full_name": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 255
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Full Name",
                                        "description": "The name to show."
                                    },
                                    "first_name": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 100
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "First Name",
                                        "description": "Given name."
                                    },
                                    "last_name": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 100
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Last Name",
                                        "description": "Family name."
                                    },
                                    "emails": {
                                        "items": {
                                            "$ref": "#/components/schemas/EmailInput"
                                        },
                                        "type": "array",
                                        "maxItems": 10,
                                        "title": "Emails",
                                        "description": "Addresses: each an `address` and optional `type` (work, home)."
                                    },
                                    "phones": {
                                        "items": {
                                            "$ref": "#/components/schemas/PhoneInput"
                                        },
                                        "type": "array",
                                        "maxItems": 10,
                                        "title": "Phones",
                                        "description": "Numbers: each a `number` and optional `type`."
                                    },
                                    "organization": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 255
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Organization",
                                        "description": "Company."
                                    },
                                    "title": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 255
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Title",
                                        "description": "Job title."
                                    },
                                    "address": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 500
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Address",
                                        "description": "Postal address."
                                    },
                                    "note": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 2000
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Note",
                                        "description": "Notes."
                                    },
                                    "birthday": {
                                        "anyOf": [
                                            {
                                                "type": "string",
                                                "maxLength": 32
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ],
                                        "title": "Birthday",
                                        "description": "YYYY-MM-DD."
                                    }
                                },
                                "type": "object",
                                "title": "ContactInput",
                                "description": "The contact. Every field is optional; a contact can be just a phone number."
                            },
                            "example": {
                                "full_name": "Tunde Bello",
                                "emails": [
                                    {
                                        "address": "tunde@example.com",
                                        "type": "work"
                                    }
                                ],
                                "phones": [
                                    {
                                        "number": "+234 803 000 0000",
                                        "type": "mobile"
                                    }
                                ],
                                "organization": "Example Ltd"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/MailboxEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": {
                                                            "type": "string"
                                                        },
                                                        "etag": {
                                                            "type": "string",
                                                            "description": "The new etag."
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Contact saved successfully",
                                    "data": {
                                        "id": "5d41402a.vcf",
                                        "etag": "\"beef01\""
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "No name, address or number.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "412": {
                        "description": "`This contact changed elsewhere. Reopen it and try again.`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Mailbox API"
                ],
                "summary": "Delete a contact",
                "operationId": "delete_contact_api_v1_mailbox_address_book_contacts__card_id__delete",
                "parameters": [
                    {
                        "name": "card_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "title": "Card Id"
                        }
                    },
                    {
                        "name": "etag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "anyOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ],
                            "title": "Etag"
                        }
                    },
                    {
                        "name": "book",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "default": "default",
                            "title": "Book"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                },
                                "example": {
                                    "type": "success",
                                    "msg": "Contact deleted successfully"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Contact not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MailboxEnvelope"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "MailboxToken": []
                    }
                ],
                "description": "\n\n**Errors**\n\n| Status | When |\n|---|---|\n| `401` | No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`. |\n| `403` | The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`. |\n| `404` | Contact not found. |"
            },
            "servers": [
                {
                    "url": "https://courier.mailyte.com",
                    "description": "Mailyte's mail server, which serves the Mailbox API"
                },
                {
                    "url": "{mail_server}",
                    "description": "A self-hosted mail server",
                    "variables": {
                        "mail_server": {
                            "default": "https://mail.example.com",
                            "description": "Your mail server's address"
                        }
                    }
                }
            ]
        }
    }
}
