{
  "openapi": "3.0.3",
  "info": {
    "title": "mail1h Developer API",
    "version": "1.0.0",
    "description": "Inbound-only disposable inboxes for QA, automation and AI agents. Auth via X-API-Key header."
  },
  "servers": [{ "url": "https://api.mail1h.example", "description": "Production (đổi thành domain thật)" }],
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "schemas": {
      "Inbox": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "id": { "type": "string" },
          "address": { "type": "string" },
          "expires_at": { "type": "integer", "nullable": true }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "from_addr": { "type": "string", "nullable": true },
          "subject": { "type": "string", "nullable": true },
          "preview": { "type": "string", "nullable": true },
          "received_at": { "type": "integer" }
        }
      },
      "FullMessage": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "inbox_id": { "type": "string" },
          "from": { "type": "string", "nullable": true },
          "subject": { "type": "string", "nullable": true },
          "otp": { "type": "string", "nullable": true },
          "text": { "type": "string", "nullable": true },
          "html": { "type": "string", "nullable": true },
          "received_at": { "type": "integer" }
        }
      }
    }
  },
  "security": [{ "ApiKey": [] }],
  "paths": {
    "/api/v1/inbox": {
      "post": {
        "summary": "Create inbox",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "type": "object", "properties": { "name": { "type": "string" } } }
            }
          }
        },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } },
          "402": { "description": "Quota exceeded" },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/api/v1/inbox/{id}/messages": {
      "get": {
        "summary": "List messages",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "ok": { "type": "boolean" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/messages/{id}": {
      "get": {
        "summary": "Get message (with extracted OTP)",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "$ref": "#/components/schemas/FullMessage" } } } } }
          }
        }
      }
    },
    "/api/v1/inbox/{id}": {
      "delete": {
        "summary": "Delete inbox",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Deleted" } }
      }
    },
    "/api/v1/webhooks": {
      "post": {
        "summary": "Register webhook (HMAC-signed push)",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" } } } } }
        },
        "responses": { "201": { "description": "Created (returns secret once)" } }
      }
    }
  }
}