openapi: 3.1.0
info:
  title: EmptyInbox API
  description: |
    Disposable email inbox API for AI agents and developers.

    Create temporary email addresses, receive messages, and read content — all via REST.
    No browser required. Authenticate with a static API key.

    **Zero-config agent workflow:**
    1. `POST /auth/register` — create a free account and get an API key (no passkey needed)
    2. `POST /inbox` — create a disposable address
    3. Trigger an external signup/verification using that address
    4. `GET /messages` — poll until the email arrives
    5. Read the verification code or link from the message body

    Or use the [emptyinbox-mcp](https://www.npmjs.com/package/emptyinbox-mcp) package — auto-registers on first run, no setup needed.

    Human accounts: get your API key at https://emptyinbox.me/settings.html
  version: 1.1.0
  contact:
    url: https://emptyinbox.me

servers:
  - url: https://emptyinbox.me/api
    description: Production

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        Your API key. Obtain one by calling `POST /auth/register` (agents) or from https://emptyinbox.me/settings.html (humans).
        Usage: `Authorization: Bearer <your_api_key>`

  schemas:
    MessageSummary:
      type: object
      properties:
        id:
          type: string
          example: "a1b2c3d4"
        inbox:
          type: string
          example: "clever.sunny.butterfly@emptyinbox.me"
        subject:
          type: string
          example: "Confirm your email address"
        text_body:
          type: string
          example: "Your verification code is 482910"
        html_body:
          type: string
          example: "<p>Your verification code is <strong>482910</strong></p>"
        sender:
          type: string
          example: "noreply@example.com"
        timestamp:
          type: integer
          description: Unix timestamp
          example: 1711234567

    MessageFull:
      type: object
      properties:
        recipients:
          type: array
          items:
            type: string
        headers:
          type: object
          additionalProperties:
            type: string
        text_body:
          type: string
        html_body:
          type: string
        sender:
          type: string

    Inbox:
      type: object
      properties:
        inbox:
          type: string
          example: "clever.sunny.butterfly@emptyinbox.me"
        created_at:
          type: string
          format: date-time

    RegisterResult:
      type: object
      properties:
        api_key:
          type: string
          example: "eiXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        username:
          type: string
          example: "agent-k3j9f2ab"
        inbox_quota:
          type: integer
          example: 1

    QuotaResult:
      type: object
      properties:
        username:
          type: string
          example: "agent-k3j9f2ab"
        inbox_quota:
          type: integer
          example: 1

    Error:
      type: object
      properties:
        error:
          type: string

paths:
  /auth/register:
    post:
      operationId: registerAccount
      summary: Register a new agent account
      description: |
        Creates a new account and returns an API key. No passkey or browser required.
        Agent accounts start with 1 inbox quota. Rate limited to 3 registrations per IP per 24 hours.
        Save the returned `api_key` for all subsequent requests.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username]
              properties:
                username:
                  type: string
                  minLength: 3
                  maxLength: 32
                  description: Letters, numbers, hyphens, and underscores only
                  example: "agent-k3j9f2ab"
      responses:
        "200":
          description: Account created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegisterResult"
        "400":
          description: Invalid or taken username
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded (3 registrations per IP per 24 hours)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/me:
    get:
      operationId: getQuota
      summary: Get account info and remaining inbox quota
      description: Returns the authenticated account's username and remaining inbox quota.
      responses:
        "200":
          description: Account info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuotaResult"
        "401":
          description: Missing or invalid API key

  /inbox:
    post:
      operationId: createInbox
      summary: Create a new disposable email inbox
      description: |
        Creates a new inbox and returns its email address as plain text.
        Each inbox consumes 1 from your quota. Agent accounts start with 1 inbox; human accounts start with 5.
        Buy more quota at https://emptyinbox.me/inboxes.html
      responses:
        "201":
          description: Inbox created — returns the email address
          content:
            text/plain:
              schema:
                type: string
              example: clever.sunny.butterfly@emptyinbox.me
        "401":
          description: Missing or invalid API key
        "403":
          description: Insufficient inbox quota

  /inboxes:
    get:
      operationId: listInboxes
      summary: List all inboxes for this account
      description: Returns all inboxes belonging to the authenticated account, newest first.
      responses:
        "200":
          description: Array of inbox objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Inbox"
        "401":
          description: Missing or invalid API key

  /messages:
    get:
      operationId: listMessages
      summary: List all received messages
      description: |
        Returns all messages across all inboxes, newest first.
        Poll this endpoint after triggering a signup or verification flow to wait for the email.
        Messages are automatically deleted after 7 days.
      responses:
        "200":
          description: Array of messages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MessageSummary"
        "401":
          description: Missing or invalid API key

  /message/{msgid}:
    get:
      operationId: getMessage
      summary: Get full content of a specific message
      description: Returns the raw parsed email content including all headers and body parts.
      parameters:
        - name: msgid
          in: path
          required: true
          schema:
            type: string
          example: a1b2c3d4
      responses:
        "200":
          description: Full message content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageFull"
        "401":
          description: Missing or invalid API key
        "404":
          description: Message not found
