{
  "openapi": "3.1.0",
  "info": {
    "title": "Mailvator TestLab API",
    "version": "1.0.0",
    "description": "Private email-testing API for Mailvator TestLab workspaces. Never expose API keys in browser code."
  },
  "servers": [{ "url": "https://mailvator.com" }],
  "security": [{ "apiKey": [] }],
  "paths": {
    "/api/v1/inboxes": {
      "post": {
        "summary": "Create or renew a private test inbox",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInbox" } } } },
        "responses": { "201": { "description": "Inbox address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/v1/messages": {
      "get": {
        "summary": "List newest workspace or inbox messages",
        "parameters": [
          { "name": "inbox", "in": "query", "schema": { "type": "string" }, "description": "Optional inbox alias" },
          { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Search sender, subject and plain-text body" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }
        ],
        "responses": { "200": { "description": "Message summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSummary" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/v1/messages/{messageId}": {
      "get": {
        "summary": "Fetch one private message",
        "parameters": [{ "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Full message with extracted OTP and links" }, "404": { "description": "Message not found" } }
      }
    },
    "/api/v1/messages/wait": {
      "get": {
        "summary": "Wait up to 25 seconds for a new inbox message",
        "parameters": [
          { "name": "inbox", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "after", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "timeout", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 20 } }
        ],
        "responses": { "200": { "description": "First matching message, or a timed-out response" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/v1/inboxes/{alias}": {
      "delete": {
        "summary": "Delete an inbox and all of its messages",
        "parameters": [{ "name": "alias", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Inbox deleted" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "mv_live_..." } },
    "responses": { "Unauthorized": { "description": "Missing, invalid or revoked API key" } },
    "schemas": {
      "CreateInbox": { "type": "object", "required": ["alias"], "properties": { "alias": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z0-9._-]+$" } } },
      "Inbox": { "type": "object", "properties": { "alias": { "type": "string" }, "address": { "type": "string", "format": "email" } } },
      "MessageSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "inbox_alias": { "type": "string" }, "sender": { "type": "string" }, "subject": { "type": "string" }, "preview": { "type": "string" }, "otp": { "type": ["string", "null"] }, "links": { "type": "array", "items": { "type": "string", "format": "uri" } }, "received_at": { "type": "string", "format": "date-time" } } }
    }
  }
}