{
  "openapi": "3.1.0",
  "info": {
    "title": "anondev.tech Mail & AI Inbox API",
    "version": "1.0.0",
    "description": "Serverless Cloudflare Email Routing + D1 inbox API for *@anondev.tech. Ideal for AI agents, automated signup verification, and personal webmail."
  },
  "servers": [
    {
      "url": "https://mail.anondev.tech"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Health check (public)",
        "security": []
      }
    },
    "/api/emails": {
      "get": {
        "summary": "List/search emails",
        "parameters": [
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by recipient (e.g. test or test@anondev.tech)"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Keyword search across subject, body, sender, code"
          },
          {
            "name": "unread",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "inbound",
                "outbound"
              ]
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Unix timestamp in milliseconds"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ]
      },
      "delete": {
        "summary": "Bulk delete emails by recipient or timestamp",
        "parameters": [
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ]
      }
    },
    "/api/emails/{id}": {
      "get": {
        "summary": "Get full email detail including text, HTML, headers, and extracted verification_code"
      },
      "patch": {
        "summary": "Update is_read status ({ is_read: 0 | 1 })"
      },
      "delete": {
        "summary": "Delete a single email"
      }
    },
    "/api/mailboxes": {
      "get": {
        "summary": "List distinct recipient addresses (*@domain) with counts"
      }
    },
    "/api/latest": {
      "get": {
        "summary": "Get the single latest matching email and extracted verification_code (AI-friendly)",
        "parameters": [
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "code_only",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ]
      }
    },
    "/api/wait": {
      "get": {
        "summary": "Long-poll up to 25s waiting for a new email/verification code to arrive",
        "parameters": [
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "timeout",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 25
            }
          }
        ]
      }
    },
    "/api/aliases/random": {
      "post": {
        "summary": "Generate a random catch-all alias on the domain"
      }
    },
    "/api/send": {
      "post": {
        "summary": "Send outbound email via Resend (requires RESEND_API_KEY secret)"
      }
    }
  }
}