{
  "openapi": "3.1.0",
  "info": {
    "title": "dissolve.email API",
    "version": "1.0.0",
    "description": "The scoped API of dissolve.email: disposable inboxes, messages, verification codes, agent identities, the vault, webhooks, rules and labels.\n\nAuthenticate with an API key (`sk_live_`, Pro and Business) or an OAuth access token (`dna_at_`) as `Authorization: Bearer <token>`. An OAuth token needs the scope named on each operation; an API key has every scope.\n\nEvery /v1 path is also served under /api/v1 for SDKs and CLIs built for destroy.network. Errors are `{ \"error\": { \"code\", \"message\", \"details\"? } }`.",
    "contact": {
      "email": "support@dissolve.email",
      "url": "https://docs.dissolve.email"
    }
  },
  "servers": [
    {
      "url": "https://api.dissolve.email"
    }
  ],
  "tags": [
    {
      "name": "Account",
      "description": "The credential, the account and the receiving domains."
    },
    {
      "name": "Inboxes",
      "description": "Disposable inboxes: create, read, extend, forward, delete."
    },
    {
      "name": "Aliases",
      "description": "More addresses that deliver into one inbox."
    },
    {
      "name": "Messages",
      "description": "Mail in an inbox and its attachments."
    },
    {
      "name": "Waiting",
      "description": "Long-polls that answer when mail or a verification code arrives."
    },
    {
      "name": "Labels",
      "description": "Named colours on messages."
    },
    {
      "name": "Identities",
      "description": "Agent identities: an inbox, a password and an optional persona for one sign-up."
    },
    {
      "name": "Vault",
      "description": "Saved credentials, encrypted at rest."
    },
    {
      "name": "Webhooks",
      "description": "Signed HTTPS deliveries for new mail and inbox events."
    },
    {
      "name": "Rules",
      "description": "Forward, label or delete new mail by sender or subject."
    },
    {
      "name": "Templates",
      "description": "Saved inbox settings."
    },
    {
      "name": "OAuth",
      "description": "The OAuth 2.1 authorization server (PKCE S256) and its discovery documents."
    },
    {
      "name": "CLI",
      "description": "The device flow the dna CLI signs in with."
    }
  ],
  "paths": {
    "/api/cli/device": {
      "post": {
        "operationId": "postApiCliDevice",
        "tags": [
          "CLI"
        ],
        "summary": "Start the CLI device flow",
        "description": "Asks for a one-time code to show the person and a device code to poll with. The person opens `verification_url`, checks the code and approves. Ten a minute per address.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "device_code": "dc_...",
                  "user_code": "WDJB-MJHT",
                  "verification_url": "https://app.dissolve.email/cli/auth",
                  "expires_in": 600,
                  "interval": 5
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/api/cli/token": {
      "post": {
        "operationId": "postApiCliToken",
        "tags": [
          "CLI"
        ],
        "summary": "Poll for the CLI's key",
        "description": "Answers 400 `authorization_pending` until the person approves, then once with a new `sk_live_` key (Pro and Business). `access_denied` and `expired_token` end the flow.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "device_code": {
                    "type": "string",
                    "description": "From POST /api/cli/device."
                  }
                },
                "required": [
                  "device_code"
                ]
              },
              "example": {
                "device_code": "dc_..."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "api_key": "sk_live_..."
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/v1/connection": {
      "get": {
        "operationId": "getV1Connection",
        "tags": [
          "Account"
        ],
        "summary": "Describe this credential",
        "description": "What the bearer credential is: an API key (`kind` user or cli, scopes `*`) or an OAuth connection (`kind` mcp or app, the scopes the person approved), its per-minute rate and the resource an OAuth token was issued for. Needs no scope.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "kind": "user",
                  "clientId": null,
                  "scopes": [
                    "*"
                  ],
                  "requestsPerMinute": 100,
                  "resource": null
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": []
          }
        ],
        "x-scope": null
      }
    },
    "/v1/me": {
      "get": {
        "operationId": "getV1Me",
        "tags": [
          "Account"
        ],
        "summary": "Get the account and its limits",
        "description": "The account id, plan, subscription status and the limits that matter to an API caller. The email address is included only when the connection has the `email` scope.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "usr7Np2QkX9mVc4Rt1ZbL",
                  "email": "you@example.com",
                  "plan": "pro",
                  "subscriptionStatus": "active",
                  "limits": {
                    "maxInboxes": 10,
                    "inboxDurationMinutes": 30,
                    "maxAliasesPerInbox": 5,
                    "customInboxNames": true,
                    "agentIdentities": true,
                    "maxAgentIdentities": 10,
                    "agentWaitTimeoutSeconds": 30,
                    "vault": true,
                    "requestsPerMinute": 100
                  },
                  "connection": {
                    "kind": "user",
                    "clientId": null,
                    "scopes": [
                      "*"
                    ]
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "profile"
            ]
          }
        ],
        "x-scope": "profile"
      }
    },
    "/v1/domains": {
      "get": {
        "operationId": "getV1Domains",
        "tags": [
          "Account"
        ],
        "summary": "List the domains for new addresses",
        "description": "The receiving domains a new inbox or identity can use, and the default. Pro and Business may choose one with `domain` when creating; Free always gets the default.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "domains": [
                    {
                      "id": "d-0",
                      "domain": "dissolve.email",
                      "isDefault": true
                    }
                  ],
                  "defaultDomain": "dissolve.email"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": []
          }
        ],
        "x-scope": null
      }
    },
    "/v1/inboxes": {
      "get": {
        "operationId": "getV1Inboxes",
        "tags": [
          "Inboxes"
        ],
        "summary": "List inboxes",
        "description": "Every inbox on the account that has not expired, newest first.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": [
                  {
                    "id": "V1StGXR8Z5jdHi6BmyT2k",
                    "address": "k3v9q2xa@dissolve.email",
                    "domain": "dissolve.email",
                    "expiresAt": "2026-11-19T10:30:00.000Z",
                    "createdAt": "2026-11-19T10:00:00.000Z",
                    "customName": null
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:read"
            ]
          }
        ],
        "x-scope": "inboxes:read"
      },
      "post": {
        "operationId": "postV1Inboxes",
        "tags": [
          "Inboxes"
        ],
        "summary": "Create an inbox",
        "description": "Makes a disposable inbox that expires after the plan's lifetime (Free 10 minutes, Pro 30, Business 60). With no body the address is random. Counts against the plan's active inboxes and, on Free, five creations an hour.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "customName": {
                    "type": "string",
                    "description": "The local part to use, such as signup-test (Pro and Business): 3 to 32 letters, digits, dots, hyphens and underscores, starting and ending with a letter or digit. Reserved names are refused."
                  },
                  "domain": {
                    "type": "string",
                    "description": "A domain from GET /v1/domains (Pro and Business). Omit for the default."
                  },
                  "templateId": {
                    "type": "string",
                    "description": "A template from GET /v1/templates: its domain and forwarding address are applied."
                  }
                }
              },
              "example": {
                "customName": "signup-test"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "V1StGXR8Z5jdHi6BmyT2k",
                  "address": "signup-test@dissolve.email",
                  "domain": "dissolve.email",
                  "expiresAt": "2026-11-19T10:30:00.000Z",
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "customName": "signup-test",
                  "isReserved": false,
                  "forwardTo": null
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:write"
            ]
          }
        ],
        "x-scope": "inboxes:write"
      }
    },
    "/v1/inboxes/{id}": {
      "get": {
        "operationId": "getV1InboxesId",
        "tags": [
          "Inboxes"
        ],
        "summary": "Get an inbox",
        "description": "One inbox with its expiry, whether it can be extended now, forwarding (owner only) and your role (`owner`, or `member` for an inbox a team shares with you). An expired inbox answers 410.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "V1StGXR8Z5jdHi6BmyT2k",
                  "address": "k3v9q2xa@dissolve.email",
                  "domain": "dissolve.email",
                  "expiresAt": "2026-11-19T10:30:00.000Z",
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "customName": null,
                  "extensionCount": 0,
                  "maxExtensions": null,
                  "canExtend": false,
                  "extendAvailableAt": "2026-11-19T10:15:00.000Z",
                  "extendCooldownActive": true,
                  "lifetimeReached": false,
                  "maxTotalLifetimeMinutes": 1440,
                  "forwardTo": null,
                  "canForward": true,
                  "ownerTier": "pro",
                  "role": "owner",
                  "sharedWithTeamId": null
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:read"
            ]
          }
        ],
        "x-scope": "inboxes:read"
      },
      "patch": {
        "operationId": "patchV1InboxesId",
        "tags": [
          "Inboxes"
        ],
        "summary": "Set or clear forwarding",
        "description": "Forwards every new message to a real address, or stops forwarding with null (Pro and Business, owner only). Addresses on dissolve.email and known disposable services are refused.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "forwardTo": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "email",
                    "description": "Where to forward, or null to stop."
                  }
                },
                "required": [
                  "forwardTo"
                ]
              },
              "example": {
                "forwardTo": "me@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "V1StGXR8Z5jdHi6BmyT2k",
                  "address": "k3v9q2xa@dissolve.email",
                  "domain": "dissolve.email",
                  "forwardTo": "me@example.com",
                  "expiresAt": "2026-11-19T10:30:00.000Z",
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "message": "Emails will now be forwarded to me@example.com"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:write"
            ]
          }
        ],
        "x-scope": "inboxes:write",
        "x-plan": "pro"
      },
      "delete": {
        "operationId": "deleteV1InboxesId",
        "tags": [
          "Inboxes"
        ],
        "summary": "Delete an inbox",
        "description": "Deletes the inbox, its messages, attachments and aliases now (owner only). A reserved name (Business) stays held for the plan's reservation days.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:write"
            ]
          }
        ],
        "x-scope": "inboxes:write"
      }
    },
    "/v1/inboxes/{id}/extend": {
      "post": {
        "operationId": "postV1InboxesIdExtend",
        "tags": [
          "Inboxes"
        ],
        "summary": "Extend an inbox",
        "description": "Adds the plan's extension time (Free 10 minutes once; Pro 30 and Business 60, as often as you like). On Pro and Business an inbox can be extended only when it has 15 (Pro) or 30 (Business) minutes or less left, and never past the plan's longest life (24 hours on Pro, 72 on Business).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "V1StGXR8Z5jdHi6BmyT2k",
                  "address": "k3v9q2xa@dissolve.email",
                  "domain": "dissolve.email",
                  "expiresAt": "2026-11-19T11:00:00.000Z",
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "extensionCount": 1,
                  "maxExtensions": null,
                  "canExtend": false,
                  "extendAvailableAt": "2026-11-19T10:45:00.000Z",
                  "extendCooldownActive": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:write"
            ]
          }
        ],
        "x-scope": "inboxes:write"
      }
    },
    "/v1/inboxes/{id}/aliases": {
      "get": {
        "operationId": "getV1InboxesIdAliases",
        "tags": [
          "Aliases"
        ],
        "summary": "List an inbox's aliases",
        "description": "Other addresses that deliver into this inbox, newest first.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": [
                  {
                    "id": "als6Rb1TnW8qXk3Zm5PcV",
                    "aliasAddress": "billing@dissolve.email",
                    "createdAt": "2026-11-19T10:01:00.000Z"
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:read"
            ]
          }
        ],
        "x-scope": "inboxes:read"
      },
      "post": {
        "operationId": "postV1InboxesIdAliases",
        "tags": [
          "Aliases"
        ],
        "summary": "Create an alias",
        "description": "Adds another address on the inbox's domain (Pro 5 per inbox, Business 25; owner only).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "alias": {
                    "type": "string",
                    "maxLength": 50,
                    "description": "The local part: lower case letters, digits and inner hyphens."
                  }
                },
                "required": [
                  "alias"
                ]
              },
              "example": {
                "alias": "billing"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "als6Rb1TnW8qXk3Zm5PcV",
                  "aliasAddress": "billing@dissolve.email",
                  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
                  "createdAt": "2026-11-19T10:01:00.000Z",
                  "message": "Alias billing@dissolve.email created. Mail to it lands in this inbox."
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:write"
            ]
          }
        ],
        "x-scope": "inboxes:write",
        "x-plan": "pro"
      }
    },
    "/v1/inboxes/{id}/aliases/{aliasId}": {
      "delete": {
        "operationId": "deleteV1InboxesIdAliasesAliasId",
        "tags": [
          "Aliases"
        ],
        "summary": "Delete an alias",
        "description": "Removes the alias. Its address is held back for a while before anyone else can take it.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "aliasId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Alias billing@dissolve.email deleted."
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:write"
            ]
          }
        ],
        "x-scope": "inboxes:write"
      }
    },
    "/v1/inboxes/{id}/messages": {
      "get": {
        "operationId": "getV1InboxesIdMessages",
        "tags": [
          "Messages"
        ],
        "summary": "List messages",
        "description": "Messages in the inbox, newest first, bodies included. Listing is held to five calls a minute per credential: to wait for mail, use GET /v1/inboxes/{id}/wait instead of polling. `q` searches the newest 1,000 messages (Pro and Business) and the answer carries `X-Search-Window: 1000`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many messages to return.",
            "schema": {
              "type": "integer",
              "default": 200,
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Words to find in the subject, sender or text body (Pro and Business).",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "label",
            "in": "query",
            "required": false,
            "description": "Only messages carrying this label id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": [
                  {
                    "id": "Qm8wZ1kX0pLr7aYtV3nBc",
                    "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
                    "fromAddress": "noreply@github.com",
                    "fromName": "GitHub",
                    "subject": "Your GitHub launch code",
                    "bodyText": "Here is your GitHub launch code: 482913",
                    "bodyHtml": "<p>Here is your GitHub launch code: <b>482913</b></p>",
                    "hasAttachments": false,
                    "rawSize": 5120,
                    "receivedAt": "2026-11-19T10:02:11.000Z",
                    "authentication": {
                      "spf": "pass",
                      "dkim": "pass",
                      "dmarc": "pass",
                      "envelopeFrom": "bounces@github.com"
                    }
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read"
      }
    },
    "/v1/inboxes/{id}/messages/{messageId}": {
      "get": {
        "operationId": "getV1InboxesIdMessagesMessageId",
        "tags": [
          "Messages"
        ],
        "summary": "Get a message",
        "description": "One message in full: text and HTML bodies, size, and what the receiving server checked (SPF, DKIM, DMARC and the envelope sender). The From header is the sender's own claim.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "Qm8wZ1kX0pLr7aYtV3nBc",
                  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
                  "fromAddress": "noreply@github.com",
                  "fromName": "GitHub",
                  "subject": "Your GitHub launch code",
                  "bodyText": "Here is your GitHub launch code: 482913",
                  "bodyHtml": "<p>Here is your GitHub launch code: <b>482913</b></p>",
                  "hasAttachments": false,
                  "rawSize": 5120,
                  "receivedAt": "2026-11-19T10:02:11.000Z",
                  "authentication": {
                    "spf": "pass",
                    "dkim": "pass",
                    "dmarc": "pass",
                    "envelopeFrom": "bounces@github.com"
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read"
      }
    },
    "/v1/inboxes/{id}/messages/{messageId}/attachments": {
      "get": {
        "operationId": "getV1InboxesIdMessagesMessageIdAttachments",
        "tags": [
          "Messages"
        ],
        "summary": "List a message's attachments",
        "description": "Name, type and size of each attachment. Listing works on every plan; downloading needs Pro or Business.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": [
                  {
                    "id": "att1Xc5VbN8mQz2Rk7TpW",
                    "messageId": "Qm8wZ1kX0pLr7aYtV3nBc",
                    "filename": "invoice.pdf",
                    "contentType": "application/pdf",
                    "size": 48213,
                    "createdAt": "2026-11-19T10:02:11.000Z"
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read"
      }
    },
    "/v1/inboxes/{id}/messages/{messageId}/attachments/{attachmentId}": {
      "get": {
        "operationId": "getV1InboxesIdMessagesMessageIdAttachmentsAttachmentId",
        "tags": [
          "Messages"
        ],
        "summary": "Download an attachment",
        "description": "The file itself, served as a download (`Content-Disposition: attachment`, `nosniff`) whatever its type. Pro and Business.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "attachmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The attachment's bytes.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read",
        "x-plan": "pro"
      }
    },
    "/v1/messages/{messageId}/labels/{labelId}": {
      "put": {
        "operationId": "putV1MessagesMessageIdLabelsLabelId",
        "tags": [
          "Labels"
        ],
        "summary": "Label a message",
        "description": "Puts one of your labels on a message in an inbox you own or that a team shares with you. Doing it twice is harmless.",
        "parameters": [
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "labelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:write"
            ]
          }
        ],
        "x-scope": "messages:write",
        "x-plan": "pro"
      },
      "delete": {
        "operationId": "deleteV1MessagesMessageIdLabelsLabelId",
        "tags": [
          "Labels"
        ],
        "summary": "Take a label off a message",
        "description": "Removes one of your labels from a message.",
        "parameters": [
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "labelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:write"
            ]
          }
        ],
        "x-scope": "messages:write",
        "x-plan": "pro"
      }
    },
    "/v1/inboxes/{id}/wait": {
      "get": {
        "operationId": "getV1InboxesIdWait",
        "tags": [
          "Waiting"
        ],
        "summary": "Wait for a message",
        "description": "Holds the request until mail arrives after `since` (default: now) or `timeout` runs out, then answers with up to 20 message summaries. It sleeps on the inbox's event stream rather than polling. At most five waits may be open at once per credential.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timeout",
            "in": "query",
            "required": false,
            "description": "Seconds to wait. Capped by the plan's agentWaitTimeoutSeconds (Free 0, so it checks once) and by 300.",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 300
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Only messages received after this time. Defaults to the moment the request starts for wait, and to every message for code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Only messages whose sender address contains this text, such as github.com.",
            "schema": {
              "type": "string",
              "maxLength": 254
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "found": true,
                  "messages": [
                    {
                      "id": "Qm8wZ1kX0pLr7aYtV3nBc",
                      "fromAddress": "noreply@github.com",
                      "fromName": "GitHub",
                      "subject": "Your GitHub launch code",
                      "receivedAt": "2026-11-19T10:02:11.000Z"
                    }
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read"
      }
    },
    "/v1/inboxes/{id}/code": {
      "get": {
        "operationId": "getV1InboxesIdCode",
        "tags": [
          "Waiting"
        ],
        "summary": "Wait for a verification code",
        "description": "As wait, but answers with the first verification code, one-time password or magic link found, with the message it came from. Without `since` it also looks at mail already in the inbox. `found` is false when nothing turned up in time.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timeout",
            "in": "query",
            "required": false,
            "description": "Seconds to wait. Capped by the plan's agentWaitTimeoutSeconds (Free 0, so it checks once) and by 300.",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 300
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Only messages received after this time. Defaults to the moment the request starts for wait, and to every message for code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Only messages whose sender address contains this text, such as github.com.",
            "schema": {
              "type": "string",
              "maxLength": 254
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "found": true,
                  "type": "code",
                  "value": "482913",
                  "confidence": 0.95,
                  "message": {
                    "id": "Qm8wZ1kX0pLr7aYtV3nBc",
                    "fromAddress": "noreply@github.com",
                    "fromName": "GitHub",
                    "subject": "Your GitHub launch code",
                    "receivedAt": "2026-11-19T10:02:11.000Z"
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read"
      }
    },
    "/v1/identities": {
      "get": {
        "operationId": "getV1Identities",
        "tags": [
          "Identities"
        ],
        "summary": "List identities",
        "description": "Live agent identities with their passwords (Pro and Business). `expired=true` includes expired ones.",
        "parameters": [
          {
            "name": "expired",
            "in": "query",
            "required": false,
            "description": "Include identities whose inbox has expired.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "identities": [
                    {
                      "id": "idn4Rk2PqT9wYc1Lm0ZxA",
                      "email": "signup7f2k@dissolve.email",
                      "password": "w8#Kq2!vLz9@pR4m",
                      "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
                      "label": "GitHub test account",
                      "expiresAt": "2026-11-19T10:30:00.000Z",
                      "expired": false,
                      "createdAt": "2026-11-19T10:00:00.000Z",
                      "persona": null
                    }
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "identities:read"
            ]
          }
        ],
        "x-scope": "identities:read",
        "x-plan": "pro"
      },
      "post": {
        "operationId": "postV1Identities",
        "tags": [
          "Identities"
        ],
        "summary": "Create an identity",
        "description": "Makes an inbox and a strong password for one sign-up, and with `persona` a fictional person (name, birthday, address) to fill in the form. The password comes back in the answer and stays readable with GET. Pro 10 live identities, Business 50; at most 30 new ones an hour.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "What it is for, such as GitHub test account."
                  },
                  "ttlMinutes": {
                    "type": "integer",
                    "default": 30,
                    "minimum": 1,
                    "maximum": 1440,
                    "description": "Minutes until it expires."
                  },
                  "prefix": {
                    "type": "string",
                    "maxLength": 20,
                    "description": "Start of the address (letters and digits); four random characters follow."
                  },
                  "domain": {
                    "type": "string",
                    "description": "A domain from GET /v1/domains."
                  },
                  "passwordLength": {
                    "type": "integer",
                    "default": 16,
                    "minimum": 8,
                    "maximum": 64,
                    "description": "Length of the generated password."
                  },
                  "persona": {
                    "type": "boolean",
                    "description": "Also make a fictional person."
                  },
                  "country": {
                    "type": "string",
                    "enum": [
                      "US",
                      "UK",
                      "AU",
                      "CA",
                      "DE",
                      "FR",
                      "JP",
                      "BR",
                      "IN",
                      "ES",
                      "IT",
                      "NL",
                      "KR",
                      "MX",
                      "SE",
                      "PL",
                      "NZ"
                    ],
                    "description": "The persona's country."
                  },
                  "gender": {
                    "type": "string",
                    "enum": [
                      "male",
                      "female"
                    ],
                    "description": "The persona's gender."
                  },
                  "inboxId": {
                    "type": "string",
                    "description": "Attach the identity to an inbox you already own instead of making one."
                  }
                }
              },
              "example": {
                "label": "GitHub test account",
                "ttlMinutes": 30,
                "persona": true,
                "country": "AU"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
                  "email": "signup7f2k@dissolve.email",
                  "password": "w8#Kq2!vLz9@pR4m",
                  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
                  "expiresAt": "2026-11-19T10:30:00.000Z",
                  "ttlMinutes": 30,
                  "label": "GitHub test account",
                  "persona": {
                    "firstName": "Mia",
                    "lastName": "Nguyen",
                    "fullName": "Mia Nguyen",
                    "gender": "female",
                    "country": "AU",
                    "username": "mia.nguyen84",
                    "dateOfBirth": "1984-06-12",
                    "address": {
                      "street": "14 Wattle Street",
                      "city": "Brisbane",
                      "state": "QLD",
                      "zip": "4000",
                      "formatted": "14 Wattle Street, Brisbane QLD 4000"
                    },
                    "phone": "+61 412 555 019"
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "identities:write"
            ]
          }
        ],
        "x-scope": "identities:write",
        "x-plan": "pro"
      }
    },
    "/v1/identities/{id}": {
      "get": {
        "operationId": "getV1IdentitiesId",
        "tags": [
          "Identities"
        ],
        "summary": "Get an identity",
        "description": "One identity with its password, persona and message count.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
                  "email": "signup7f2k@dissolve.email",
                  "password": "w8#Kq2!vLz9@pR4m",
                  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
                  "label": "GitHub test account",
                  "expiresAt": "2026-11-19T10:30:00.000Z",
                  "expired": false,
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "persona": null,
                  "messageCount": 1
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "identities:read"
            ]
          }
        ],
        "x-scope": "identities:read",
        "x-plan": "pro"
      },
      "patch": {
        "operationId": "patchV1IdentitiesId",
        "tags": [
          "Identities"
        ],
        "summary": "Extend or relabel an identity",
        "description": "Sets the identity to expire `ttlMinutes` from now (default: the plan's extension time) and changes its label, within the plan's longest inbox life.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ttlMinutes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1440,
                    "description": "Minutes from now until it expires."
                  },
                  "label": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "A new label."
                  }
                }
              },
              "example": {
                "ttlMinutes": 60
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
                  "expiresAt": "2026-11-19T11:05:00.000Z",
                  "ttlMinutes": 60,
                  "label": "GitHub test account"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "identities:write"
            ]
          }
        ],
        "x-scope": "identities:write",
        "x-plan": "pro"
      },
      "delete": {
        "operationId": "deleteV1IdentitiesId",
        "tags": [
          "Identities"
        ],
        "summary": "Delete an identity",
        "description": "Deletes the identity and its inbox with every message. `keepInbox=true` deletes only the identity.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keepInbox",
            "in": "query",
            "required": false,
            "description": "Keep the inbox and its mail.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "identities:write"
            ]
          }
        ],
        "x-scope": "identities:write",
        "x-plan": "pro"
      }
    },
    "/v1/identities/{id}/messages": {
      "get": {
        "operationId": "getV1IdentitiesIdMessages",
        "tags": [
          "Identities"
        ],
        "summary": "List an identity's messages",
        "description": "The newest 50 messages with a 200 character snippet each.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "messages": [
                    {
                      "id": "Qm8wZ1kX0pLr7aYtV3nBc",
                      "from": "noreply@github.com",
                      "fromName": "GitHub",
                      "subject": "Your GitHub launch code",
                      "snippet": "Here is your GitHub launch code: 482913",
                      "receivedAt": "2026-11-19T10:02:11.000Z"
                    }
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read",
        "x-plan": "pro"
      }
    },
    "/v1/identities/{id}/messages/{messageId}": {
      "get": {
        "operationId": "getV1IdentitiesIdMessagesMessageId",
        "tags": [
          "Identities"
        ],
        "summary": "Get an identity's message",
        "description": "One message with its text and HTML bodies.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "Qm8wZ1kX0pLr7aYtV3nBc",
                  "from": "noreply@github.com",
                  "fromName": "GitHub",
                  "subject": "Your GitHub launch code",
                  "bodyText": "Here is your GitHub launch code: 482913",
                  "bodyHtml": "<p>Here is your GitHub launch code: <b>482913</b></p>",
                  "snippet": "Here is your GitHub launch code: 482913",
                  "receivedAt": "2026-11-19T10:02:11.000Z"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read",
        "x-plan": "pro"
      }
    },
    "/v1/identities/{id}/wait": {
      "get": {
        "operationId": "getV1IdentitiesIdWait",
        "tags": [
          "Identities"
        ],
        "summary": "Wait for an identity's next message",
        "description": "Holds the request until a message arrives after it started, or `timeout` (default 30, capped by the plan) runs out.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timeout",
            "in": "query",
            "required": false,
            "description": "Seconds to wait, capped by the plan (Pro 30, Business 120).",
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 1,
              "maximum": 300
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "timedOut": false,
                  "message": {
                    "id": "Qm8wZ1kX0pLr7aYtV3nBc",
                    "from": "noreply@github.com",
                    "subject": "Your GitHub launch code",
                    "snippet": "Here is your GitHub launch code: 482913",
                    "receivedAt": "2026-11-19T10:02:11.000Z"
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read",
        "x-plan": "pro"
      }
    },
    "/v1/identities/{id}/code": {
      "get": {
        "operationId": "getV1IdentitiesIdCode",
        "tags": [
          "Identities"
        ],
        "summary": "Get the code sent to an identity",
        "description": "The first verification code or magic link in the identity's mail, waiting up to `timeout` seconds for one. `from` filters by sender on the server; a `pattern` parameter is ignored here (a caller's regular expression could take too long).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timeout",
            "in": "query",
            "required": false,
            "description": "Seconds to wait, capped by the plan.",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 300
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Only messages whose sender address contains this text.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "found": true,
                  "type": "code",
                  "value": "482913",
                  "confidence": 0.95,
                  "source": {
                    "messageId": "Qm8wZ1kX0pLr7aYtV3nBc",
                    "from": "noreply@github.com",
                    "subject": "Your GitHub launch code"
                  },
                  "rawMatches": [
                    {
                      "type": "code",
                      "value": "482913",
                      "confidence": 0.95
                    }
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read",
        "x-plan": "pro"
      }
    },
    "/v1/vault": {
      "get": {
        "operationId": "getV1Vault",
        "tags": [
          "Vault"
        ],
        "summary": "List vault entries",
        "description": "Saved credentials without their passwords, pinned first (Pro 50 entries, Business 500).",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Words to find in the site name, email or notes.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Only this category.",
            "schema": {
              "type": "string",
              "enum": [
                "social",
                "shopping",
                "dev-tools",
                "testing",
                "gaming",
                "finance",
                "news",
                "entertainment",
                "work",
                "other"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "entries": [
                    {
                      "id": "vlt8Yh3NcQ2mZp5Rt0WxK",
                      "email": "signup7f2k@dissolve.email",
                      "siteName": "GitHub",
                      "siteUrl": "https://github.com",
                      "category": "dev-tools",
                      "notes": null,
                      "sourceIdentityId": "idn4Rk2PqT9wYc1Lm0ZxA",
                      "pinned": false,
                      "createdAt": "2026-11-19T10:05:00.000Z",
                      "updatedAt": "2026-11-19T10:05:00.000Z"
                    }
                  ],
                  "limit": 50
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "vault:read"
            ]
          }
        ],
        "x-scope": "vault:read",
        "x-plan": "pro"
      },
      "post": {
        "operationId": "postV1Vault",
        "tags": [
          "Vault"
        ],
        "summary": "Save a credential",
        "description": "Stores an email and password for a site, encrypted at rest.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "The sign-in address."
                  },
                  "password": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "The password."
                  },
                  "siteName": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "The site, such as GitHub."
                  },
                  "siteUrl": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "The site's address."
                  },
                  "category": {
                    "type": "string",
                    "enum": [
                      "social",
                      "shopping",
                      "dev-tools",
                      "testing",
                      "gaming",
                      "finance",
                      "news",
                      "entertainment",
                      "work",
                      "other"
                    ],
                    "description": "A category."
                  },
                  "notes": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Free text."
                  },
                  "persona": {
                    "type": "string",
                    "description": "A persona as JSON text, stored encrypted."
                  },
                  "sourceIdentityId": {
                    "type": "string",
                    "description": "The identity it came from."
                  }
                },
                "required": [
                  "email",
                  "password",
                  "siteName"
                ]
              },
              "example": {
                "email": "signup7f2k@dissolve.email",
                "password": "w8#Kq2!vLz9@pR4m",
                "siteName": "GitHub",
                "siteUrl": "https://github.com",
                "category": "dev-tools",
                "sourceIdentityId": "idn4Rk2PqT9wYc1Lm0ZxA"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "vlt8Yh3NcQ2mZp5Rt0WxK",
                  "email": "signup7f2k@dissolve.email",
                  "siteName": "GitHub",
                  "siteUrl": "https://github.com",
                  "category": "dev-tools",
                  "notes": null,
                  "sourceIdentityId": "idn4Rk2PqT9wYc1Lm0ZxA",
                  "pinned": false,
                  "createdAt": "2026-11-19T10:05:00.000Z",
                  "updatedAt": "2026-11-19T10:05:00.000Z"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "vault:write"
            ]
          }
        ],
        "x-scope": "vault:write",
        "x-plan": "pro"
      }
    },
    "/v1/vault/{id}": {
      "get": {
        "operationId": "getV1VaultId",
        "tags": [
          "Vault"
        ],
        "summary": "Get a vault entry",
        "description": "One entry with its password and persona.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "vlt8Yh3NcQ2mZp5Rt0WxK",
                  "email": "signup7f2k@dissolve.email",
                  "siteName": "GitHub",
                  "siteUrl": "https://github.com",
                  "category": "dev-tools",
                  "notes": null,
                  "sourceIdentityId": "idn4Rk2PqT9wYc1Lm0ZxA",
                  "pinned": false,
                  "createdAt": "2026-11-19T10:05:00.000Z",
                  "updatedAt": "2026-11-19T10:05:00.000Z",
                  "password": "w8#Kq2!vLz9@pR4m",
                  "persona": null
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "vault:read"
            ]
          }
        ],
        "x-scope": "vault:read",
        "x-plan": "pro"
      },
      "patch": {
        "operationId": "patchV1VaultId",
        "tags": [
          "Vault"
        ],
        "summary": "Change a vault entry",
        "description": "Changes the site, category, notes or pin. The email and password are fixed: save a new entry to change them.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "siteName": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "The site."
                  },
                  "siteUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "The site's address, or an empty string to clear it."
                  },
                  "category": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "social",
                      "shopping",
                      "dev-tools",
                      "testing",
                      "gaming",
                      "finance",
                      "news",
                      "entertainment",
                      "work",
                      "other",
                      null
                    ],
                    "description": "A category, or null."
                  },
                  "notes": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 1000,
                    "description": "Free text, or null."
                  },
                  "pinned": {
                    "type": "boolean",
                    "description": "Keep it at the top of the list."
                  }
                }
              },
              "example": {
                "pinned": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "updated": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "vault:write"
            ]
          }
        ],
        "x-scope": "vault:write",
        "x-plan": "pro"
      },
      "delete": {
        "operationId": "deleteV1VaultId",
        "tags": [
          "Vault"
        ],
        "summary": "Delete a vault entry",
        "description": "Deletes the entry for good.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "vault:write"
            ]
          }
        ],
        "x-scope": "vault:write",
        "x-plan": "pro"
      }
    },
    "/v1/webhooks": {
      "get": {
        "operationId": "getV1Webhooks",
        "tags": [
          "Webhooks"
        ],
        "summary": "List webhooks",
        "description": "Your webhook endpoints, newest first (at most 10).",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": [
                  {
                    "id": "whk2Lp9QsX4nVb7Tc1RzM",
                    "url": "https://example.com/hooks/dissolve",
                    "events": [
                      "message.received"
                    ],
                    "active": true,
                    "failureCount": 0,
                    "lastTriggeredAt": null,
                    "createdAt": "2026-11-19T10:00:00.000Z"
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "x-scope": "webhooks:manage",
        "x-plan": "pro"
      },
      "post": {
        "operationId": "postV1Webhooks",
        "tags": [
          "Webhooks"
        ],
        "summary": "Create a webhook",
        "description": "Registers an HTTPS endpoint for one or more events. With a `secret` every delivery is signed in `X-Webhook-Signature: sha256=<hex>`. Addresses on private networks are refused.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "An https:// address."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "message.received",
                        "inbox.created",
                        "inbox.expired"
                      ]
                    },
                    "description": "One or more events."
                  },
                  "secret": {
                    "type": "string",
                    "description": "16 to 256 characters you choose, used to sign each delivery."
                  }
                },
                "required": [
                  "url",
                  "events"
                ]
              },
              "example": {
                "url": "https://example.com/hooks/dissolve",
                "events": [
                  "message.received"
                ],
                "secret": "a-long-random-secret-you-keep"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "whk2Lp9QsX4nVb7Tc1RzM",
                  "url": "https://example.com/hooks/dissolve",
                  "events": [
                    "message.received"
                  ],
                  "active": true,
                  "createdAt": "2026-11-19T10:00:00.000Z"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "x-scope": "webhooks:manage",
        "x-plan": "pro"
      }
    },
    "/v1/webhooks/{id}": {
      "get": {
        "operationId": "getV1WebhooksId",
        "tags": [
          "Webhooks"
        ],
        "summary": "Get a webhook",
        "description": "One endpoint with its last failure.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "whk2Lp9QsX4nVb7Tc1RzM",
                  "url": "https://example.com/hooks/dissolve",
                  "events": [
                    "message.received"
                  ],
                  "active": true,
                  "failureCount": 0,
                  "lastTriggeredAt": null,
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "lastFailureAt": null,
                  "lastFailureReason": null
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "x-scope": "webhooks:manage",
        "x-plan": "pro"
      },
      "patch": {
        "operationId": "patchV1WebhooksId",
        "tags": [
          "Webhooks"
        ],
        "summary": "Change a webhook",
        "description": "Changes the address, events or secret, or switches it on or off. Switching it on clears the failure count.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "A new https:// address."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "message.received",
                        "inbox.created",
                        "inbox.expired"
                      ]
                    },
                    "description": "The events."
                  },
                  "secret": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "A new secret, or null to stop signing."
                  },
                  "active": {
                    "type": "boolean",
                    "description": "On or off."
                  }
                }
              },
              "example": {
                "active": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "x-scope": "webhooks:manage",
        "x-plan": "pro"
      },
      "delete": {
        "operationId": "deleteV1WebhooksId",
        "tags": [
          "Webhooks"
        ],
        "summary": "Delete a webhook",
        "description": "Removes the endpoint.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "x-scope": "webhooks:manage",
        "x-plan": "pro"
      }
    },
    "/v1/labels": {
      "get": {
        "operationId": "getV1Labels",
        "tags": [
          "Labels"
        ],
        "summary": "List labels",
        "description": "Your labels, by name, with how many your plan allows (Pro 10, Business 50).",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "labels": [
                    {
                      "id": "lbl5Tq8WmZ1rXc3Vn7KpA",
                      "name": "Receipts",
                      "color": "#8b5cf6",
                      "createdAt": "2026-11-19T10:00:00.000Z"
                    }
                  ],
                  "limit": 10,
                  "used": 1
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "x-scope": "messages:read",
        "x-plan": "pro"
      },
      "post": {
        "operationId": "postV1Labels",
        "tags": [
          "Labels"
        ],
        "summary": "Create a label",
        "description": "A named colour to put on messages, by hand or by a rule.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 50,
                    "description": "Unique on the account."
                  },
                  "color": {
                    "type": "string",
                    "default": "#8b5cf6",
                    "description": "A hex colour such as #8b5cf6."
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "Receipts",
                "color": "#8b5cf6"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "lbl5Tq8WmZ1rXc3Vn7KpA",
                  "name": "Receipts",
                  "color": "#8b5cf6",
                  "createdAt": "2026-11-19T10:00:00.000Z"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage",
        "x-plan": "pro"
      }
    },
    "/v1/labels/{id}": {
      "patch": {
        "operationId": "patchV1LabelsId",
        "tags": [
          "Labels"
        ],
        "summary": "Change a label",
        "description": "Renames or recolours a label.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 50,
                    "description": "A new name."
                  },
                  "color": {
                    "type": "string",
                    "description": "A new hex colour."
                  }
                }
              },
              "example": {
                "name": "Invoices"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage",
        "x-plan": "pro"
      },
      "delete": {
        "operationId": "deleteV1LabelsId",
        "tags": [
          "Labels"
        ],
        "summary": "Delete a label",
        "description": "Deletes the label and takes it off every message.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage",
        "x-plan": "pro"
      }
    },
    "/v1/rules": {
      "get": {
        "operationId": "getV1Rules",
        "tags": [
          "Rules"
        ],
        "summary": "List rules",
        "description": "Your inbox rules, highest priority first, with how many your plan allows (Pro 10, Business 50).",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "rules": [
                    {
                      "id": "rul3Kd7PxN2qVw9Zc4TmB",
                      "name": "Label receipts",
                      "fromPattern": null,
                      "subjectPattern": "*receipt*",
                      "action": "label",
                      "actionValue": "Receipts",
                      "enabled": true,
                      "priority": 0,
                      "createdAt": "2026-11-19T10:00:00.000Z",
                      "updatedAt": "2026-11-19T10:00:00.000Z"
                    }
                  ],
                  "limit": 10,
                  "used": 1
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage",
        "x-plan": "pro"
      },
      "post": {
        "operationId": "postV1Rules",
        "tags": [
          "Rules"
        ],
        "summary": "Create a rule",
        "description": "A rule runs on every new message in your inboxes: when the sender or subject matches its glob pattern (`*` any run of characters, `?` one character, case ignored), it forwards, labels or deletes the message. At least one pattern is needed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "What the rule is for."
                  },
                  "from_pattern": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 200,
                    "description": "Glob matched against the sender address, such as *@github.com."
                  },
                  "subject_pattern": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 200,
                    "description": "Glob matched against the subject, such as *receipt*."
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "forward",
                      "delete",
                      "label"
                    ],
                    "description": "What to do with a match."
                  },
                  "action_value": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 255,
                    "description": "The address to forward to, or the label name to apply."
                  },
                  "enabled": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether it runs."
                  },
                  "priority": {
                    "type": "integer",
                    "default": 0,
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Higher runs first."
                  }
                },
                "required": [
                  "name",
                  "action"
                ]
              },
              "example": {
                "name": "Label receipts",
                "subject_pattern": "*receipt*",
                "action": "label",
                "action_value": "Receipts"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "rul3Kd7PxN2qVw9Zc4TmB",
                  "name": "Label receipts",
                  "fromPattern": null,
                  "subjectPattern": "*receipt*",
                  "action": "label",
                  "actionValue": "Receipts",
                  "enabled": true,
                  "priority": 0,
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "updatedAt": "2026-11-19T10:00:00.000Z"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage",
        "x-plan": "pro"
      }
    },
    "/v1/rules/{id}": {
      "get": {
        "operationId": "getV1RulesId",
        "tags": [
          "Rules"
        ],
        "summary": "Get a rule",
        "description": "One rule.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "rul3Kd7PxN2qVw9Zc4TmB",
                  "name": "Label receipts",
                  "fromPattern": null,
                  "subjectPattern": "*receipt*",
                  "action": "label",
                  "actionValue": "Receipts",
                  "enabled": true,
                  "priority": 0,
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "updatedAt": "2026-11-19T10:00:00.000Z"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage",
        "x-plan": "pro"
      },
      "patch": {
        "operationId": "patchV1RulesId",
        "tags": [
          "Rules"
        ],
        "summary": "Change a rule",
        "description": "Changes any field; the rule is checked again as a whole.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "What the rule is for."
                  },
                  "from_pattern": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Sender glob, or null."
                  },
                  "subject_pattern": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Subject glob, or null."
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "forward",
                      "delete",
                      "label"
                    ],
                    "description": "What to do with a match."
                  },
                  "action_value": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Forward address or label name."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Whether it runs."
                  },
                  "priority": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Higher runs first."
                  }
                }
              },
              "example": {
                "enabled": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage",
        "x-plan": "pro"
      },
      "delete": {
        "operationId": "deleteV1RulesId",
        "tags": [
          "Rules"
        ],
        "summary": "Delete a rule",
        "description": "Deletes the rule.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage",
        "x-plan": "pro"
      }
    },
    "/v1/templates": {
      "get": {
        "operationId": "getV1Templates",
        "tags": [
          "Templates"
        ],
        "summary": "List templates",
        "description": "Saved inbox settings (domain, forwarding, a webhook address) to create inboxes from, default first (Free 3, Pro 10, Business 25).",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "templates": [
                    {
                      "id": "tpl9Wm2QxK5rNc8Vz1LpT",
                      "name": "Forwarded",
                      "domain": null,
                      "forwardTo": "me@example.com",
                      "webhookUrl": null,
                      "isDefault": true,
                      "createdAt": "2026-11-19T10:00:00.000Z",
                      "updatedAt": "2026-11-19T10:00:00.000Z"
                    }
                  ],
                  "limit": 10,
                  "used": 1
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "inboxes:read"
            ]
          }
        ],
        "x-scope": "inboxes:read"
      },
      "post": {
        "operationId": "postV1Templates",
        "tags": [
          "Templates"
        ],
        "summary": "Create a template",
        "description": "Saves settings to pass as `templateId` when creating an inbox. Forwarding needs Pro or Business.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "The template's name."
                  },
                  "domain": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "A domain from GET /v1/domains."
                  },
                  "forward_to": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "email",
                    "description": "Forward new inboxes' mail here (Pro and Business)."
                  },
                  "webhook_url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uri",
                    "description": "A webhook address kept with the template."
                  },
                  "is_default": {
                    "type": "boolean",
                    "default": false,
                    "description": "Use it when no template is named."
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "Forwarded",
                "forward_to": "me@example.com",
                "is_default": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "id": "tpl9Wm2QxK5rNc8Vz1LpT",
                  "name": "Forwarded",
                  "domain": null,
                  "forwardTo": "me@example.com",
                  "webhookUrl": null,
                  "isDefault": true,
                  "createdAt": "2026-11-19T10:00:00.000Z",
                  "updatedAt": "2026-11-19T10:00:00.000Z"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage"
      }
    },
    "/v1/templates/{id}": {
      "delete": {
        "operationId": "deleteV1TemplatesId",
        "tags": [
          "Templates"
        ],
        "summary": "Delete a template",
        "description": "Deletes the template. Inboxes made from it are unchanged.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "success": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "rules:manage"
            ]
          }
        ],
        "x-scope": "rules:manage"
      }
    },
    "/oauth/register": {
      "post": {
        "operationId": "postOauthRegister",
        "tags": [
          "OAuth"
        ],
        "summary": "Register a client",
        "description": "Dynamic client registration (RFC 7591) for public clients: no secret, PKCE required. Ten registrations a minute and 20 a day per address. A dynamically registered app is shown as unverified on the consent page.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "redirect_uris": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Where the person comes back to: https, or http to localhost."
                  },
                  "client_name": {
                    "type": "string",
                    "description": "Shown on the consent page."
                  },
                  "client_uri": {
                    "type": "string",
                    "format": "uri",
                    "description": "The app's home page."
                  },
                  "logo_uri": {
                    "type": "string",
                    "format": "uri",
                    "description": "The app's logo."
                  },
                  "token_endpoint_auth_method": {
                    "type": "string",
                    "enum": [
                      "none"
                    ],
                    "default": "none",
                    "description": "Only public clients register here."
                  },
                  "grant_types": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "authorization_code",
                        "refresh_token"
                      ]
                    },
                    "description": "Defaults to both."
                  }
                },
                "required": [
                  "redirect_uris"
                ]
              },
              "example": {
                "client_name": "My agent",
                "redirect_uris": [
                  "http://localhost:8976/callback"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "client_id": "dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY",
                  "client_id_issued_at": 1795600000,
                  "client_name": "My agent",
                  "redirect_uris": [
                    "http://localhost:8976/callback"
                  ],
                  "grant_types": [
                    "authorization_code",
                    "refresh_token"
                  ],
                  "response_types": [
                    "code"
                  ],
                  "token_endpoint_auth_method": "none"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/oauth/authorize": {
      "get": {
        "operationId": "getOauthAuthorize",
        "tags": [
          "OAuth"
        ],
        "summary": "Start authorization",
        "description": "Sends the person to the consent page on app.dissolve.email. After they approve, the browser returns to `redirect_uri` with `code`, `state` and `iss`. The code lasts 60 seconds and works once.",
        "parameters": [
          {
            "name": "response_type",
            "in": "query",
            "required": true,
            "description": "Always code.",
            "schema": {
              "type": "string",
              "enum": [
                "code"
              ]
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "required": true,
            "description": "Your client id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "redirect_uri",
            "in": "query",
            "required": false,
            "description": "One of the client's registered addresses (optional when it has only one).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "Space-separated scopes. Unknown scopes are dropped.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Returned unchanged; check it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code_challenge",
            "in": "query",
            "required": true,
            "description": "BASE64URL(SHA-256(code_verifier)), 43 characters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code_challenge_method",
            "in": "query",
            "required": true,
            "description": "Always S256.",
            "schema": {
              "type": "string",
              "enum": [
                "S256"
              ]
            }
          },
          {
            "name": "resource",
            "in": "query",
            "required": false,
            "description": "The resource the token is for: https://api.dissolve.email/v1 or https://mcp.dissolve.email/mcp-oauth.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "303": {
            "description": "A redirect to the consent page, or back to redirect_uri with error and error_description."
          }
        },
        "security": []
      }
    },
    "/oauth/token": {
      "post": {
        "operationId": "postOauthToken",
        "tags": [
          "OAuth"
        ],
        "summary": "Exchange a code or refresh a token",
        "description": "With `grant_type=authorization_code`, trades the code and the PKCE verifier for tokens; with `refresh_token`, trades a refresh token for new ones (each refresh token works once). Access tokens (`dna_at_`) last an hour, refresh tokens (`dna_rt_`) 30 days from their last use. Confidential clients authenticate with HTTP Basic or `client_secret`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "authorization_code",
                      "refresh_token"
                    ],
                    "description": "Which exchange."
                  },
                  "client_id": {
                    "type": "string",
                    "description": "Your client id."
                  },
                  "code": {
                    "type": "string",
                    "description": "The code from the redirect (authorization_code)."
                  },
                  "redirect_uri": {
                    "type": "string",
                    "description": "The same redirect_uri as the authorization request."
                  },
                  "code_verifier": {
                    "type": "string",
                    "description": "The PKCE verifier (authorization_code)."
                  },
                  "refresh_token": {
                    "type": "string",
                    "description": "The refresh token (refresh_token)."
                  },
                  "client_secret": {
                    "type": "string",
                    "description": "Confidential clients only."
                  }
                },
                "required": [
                  "grant_type",
                  "client_id"
                ]
              },
              "example": {
                "grant_type": "authorization_code",
                "client_id": "dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY",
                "code": "dna_ac_...",
                "redirect_uri": "http://localhost:8976/callback",
                "code_verifier": "..."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "access_token": "dna_at_...",
                  "token_type": "Bearer",
                  "expires_in": 3600,
                  "refresh_token": "dna_rt_...",
                  "scope": "profile inboxes:read messages:read"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/oauth/revoke": {
      "post": {
        "operationId": "postOauthRevoke",
        "tags": [
          "OAuth"
        ],
        "summary": "Revoke a token",
        "description": "Revokes an access or refresh token (RFC 7009) and the connection behind it. Answers 200 whether or not the token was known.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "The access or refresh token."
                  },
                  "client_id": {
                    "type": "string",
                    "description": "Your client id."
                  }
                },
                "required": [
                  "token",
                  "client_id"
                ]
              },
              "example": {
                "token": "dna_rt_...",
                "client_id": "dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Empty."
          }
        },
        "security": []
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "operationId": "get/WellKnownOauthAuthorizationServer",
        "tags": [
          "OAuth"
        ],
        "summary": "Authorization server metadata",
        "description": "RFC 8414: the endpoints, PKCE S256, the grant types and every scope. Clients discover the server from here.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "issuer": "https://api.dissolve.email",
                  "authorization_endpoint": "https://api.dissolve.email/oauth/authorize",
                  "token_endpoint": "https://api.dissolve.email/oauth/token",
                  "registration_endpoint": "https://api.dissolve.email/oauth/register",
                  "revocation_endpoint": "https://api.dissolve.email/oauth/revoke",
                  "code_challenge_methods_supported": [
                    "S256"
                  ]
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/.well-known/oauth-protected-resource": {
      "get": {
        "operationId": "get/WellKnownOauthProtectedResource",
        "tags": [
          "OAuth"
        ],
        "summary": "Protected resource metadata",
        "description": "RFC 9728 for /v1: the resource, its authorization server and scopes. A 401 from /v1 points here in `WWW-Authenticate`.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "example": {
                  "resource": "https://api.dissolve.email/v1",
                  "authorization_servers": [
                    "https://api.dissolve.email"
                  ],
                  "bearer_methods_supported": [
                    "header"
                  ]
                }
              }
            }
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An `sk_live_` API key from app.dissolve.email/dashboard/api-keys or `dna auth login`. Has every scope."
      },
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 with PKCE (S256). Access tokens start `dna_at_` and last an hour.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.dissolve.email/oauth/authorize",
            "tokenUrl": "https://api.dissolve.email/oauth/token",
            "refreshUrl": "https://api.dissolve.email/oauth/token",
            "scopes": {
              "profile": "Your account id, plan and usage.",
              "email": "The address you sign in with.",
              "inboxes:read": "Addresses, aliases and when they expire.",
              "inboxes:write": "Create, extend, rename and delete inboxes and aliases.",
              "messages:read": "Messages, attachments and verification codes in your inboxes.",
              "messages:write": "Delete and label messages.",
              "identities:read": "Addresses, personas and saved passwords.",
              "identities:write": "Create, extend and delete identities.",
              "vault:read": "Saved credentials, passwords included.",
              "vault:write": "Add, edit and delete saved credentials.",
              "webhooks:manage": "Create, change and delete webhook endpoints.",
              "rules:manage": "Inbox rules, labels and templates."
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "A stable lower-case code such as not_found, insufficient_scope, rate_limited or validation_error."
              },
              "message": {
                "type": "string",
                "description": "A sentence for a person."
              },
              "details": {
                "type": "object",
                "description": "More about the error, such as the invalid fields or the limit."
              }
            }
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "An error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "insufficient_scope",
                "message": "This connection was not given \"inboxes:write\" (manage your inboxes). Reconnect the app and approve it.",
                "details": {
                  "scope": "inboxes:write"
                }
              }
            }
          }
        }
      }
    }
  }
}
