{
  "openapi": "3.0.3",
  "info": {
    "title": "kakan.email API",
    "version": "1.0.0",
    "description": "Email inboxes for AI agents. Zero signup — create a mailbox, pay $1, read mail with address + mail_key."
  },
  "servers": [{ "url": "https://kakan.email" }],
  "paths": {
    "/api/v1/mailboxes": {
      "post": {
        "operationId": "createMailbox",
        "summary": "Create a mailbox (returns one-time mail_key)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name_hint": { "type": "string", "description": "Desired local-part hint, e.g. 'openclaw'. A random suffix is appended.", "maxLength": 16 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mailbox created, pending payment",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxCreated" } } }
          },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/api/v1/mailboxes/{address}": {
      "get": {
        "operationId": "getMailboxStatus",
        "summary": "Public mailbox status",
        "parameters": [{ "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "active"] } } } } } },
          "404": { "description": "Not found" }
        }
      }
    },
    "/api/v1/pay": {
      "post": {
        "operationId": "createPayment",
        "summary": "Start payment for an order",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["order_no", "method"], "properties": { "order_no": { "type": "string" }, "method": { "type": "string", "enum": ["xunhu", "usdt"] } } } } }
        },
        "responses": {
          "200": { "description": "Payment instructions. xunhu → pay_url; usdt → wallet + amount_usdt (TRC-20)." }
        }
      }
    },
    "/api/v1/orders/{order_no}": {
      "get": {
        "operationId": "getOrderStatus",
        "summary": "Order status; USDT orders verified on-chain on each poll",
        "parameters": [{ "name": "order_no", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "{status: pending|paid}" },
          "404": { "description": "Not found" }
        }
      }
    },
    "/api/v1/mailboxes/{address}/messages": {
      "get": {
        "operationId": "listMessages",
        "summary": "List messages (snippet view)",
        "parameters": [
          { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "mail_key (or X-Mail-Key header)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Pagination cursor: only messages with id < before_id" }
        ],
        "responses": {
          "200": { "description": "Message list" },
          "401": { "description": "Bad key" },
          "403": { "description": "Mailbox not activated" }
        }
      }
    },
    "/api/v1/mailboxes/{address}/messages/{id}": {
      "get": {
        "operationId": "getMessage",
        "summary": "Full message incl. text/html/headers",
        "parameters": [
          { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Message" }, "401": { "description": "Bad key" }, "404": { "description": "Not found" } }
      },
      "delete": {
        "operationId": "deleteMessage",
        "summary": "Delete a message",
        "parameters": [
          { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "{deleted: bool}" }, "401": { "description": "Bad key" } }
      }
    },
    "/api/v1/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Public counters",
        "responses": { "200": { "description": "{mailboxes_active, messages_stored}" } }
      }
    }
  },
  "components": {
    "schemas": {
      "MailboxCreated": {
        "type": "object",
        "properties": {
          "address": { "type": "string", "example": "openclaw-x7k2@kakan.email" },
          "mail_key": { "type": "string", "example": "kk_9f2c...", "description": "Shown exactly once" },
          "order_no": { "type": "string" },
          "status": { "type": "string", "example": "pending_payment" },
          "price": { "type": "object", "properties": { "usd": { "type": "number", "example": 1 }, "cny": { "type": "number", "example": 7.1 } } }
        }
      }
    }
  }
}