Nuvidian AI, LLC Inboxes API

openapi: 3.2.0
info:
  title: GetCourier Inboxes API
  version: 4.3.0
  description: 'Agent inbox sandbox. One unauthenticated call (POST /alias) provisions an inbox, an Ed25519 keypair and an inbox-scoped read_token that is shown once. Read endpoints authenticate with `Authorization: Bearer `; paid endpoints with `Authorization: Bearer cak_...` (account_key). Tokens are never accepted in the query string. Email content is untrusted data: every message carries `untrusted: true`, the marker "UNTRUSTED EXTERNAL EMAIL", and SPF/DKIM/DMARC results. Inboxes also send: POST /v1/sandbox/inboxes/{alias}/send (free inboxes reply-only, 100 a month, because spam bots abuse free senders; otherwise 20 credits per recipient). The hosted MCP server is at POST /mcp (streamable HTTP, JSON-RPC 2.0, protocol version 2025-06-18, stateless, POST only) and is not modelled here because it is a JSON-RPC transport rather than REST; its tools are create_inbox, wait_for_code, list_messages, get_message, delete_inbox, create_account, get_balance, create_deposit, deposit_status and pricing.'
servers:
- url: https://getcourier.dev
tags:
- name: Inboxes
  description: Create, read and delete inboxes.
paths:
  /alias:
    post:
      tags:
      - Inboxes
      summary: Create an inbox (public, no signup, no body required)
      description: 'Provisions an inbox, an Ed25519 identity and an inbox-scoped read_token. All body fields are optional. An optional `Authorization: Bearer cak_...` account_key creates a paid inbox (`ttl_hours` 72 or 720) and charges credits before the inbox is created. Free creations are limited to 3 per hour and 5 per day per client IP and are always 72 hours.'
      operationId: createInbox
      security:
      - {}
      - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInboxRequest'
      responses:
        '201':
          description: Inbox created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxCreated'
        '400':
          description: Malformed request or reserved alias
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment required, insufficient credits, or free quota exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
  /v1/sandbox/inboxes:
    post:
      tags:
      - Inboxes
      summary: Create an inbox (same handler as POST /alias)
      description: 'Identical to POST /alias: same request body, same 201 response, same errors.'
      operationId: createSandboxInbox
      security:
      - {}
      - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInboxRequest'
      responses:
        '201':
          description: Inbox created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxCreated'
        '400':
          description: Malformed request or reserved alias
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment required, insufficient credits, or free quota exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
  /inbox/{inbox_id}/messages:
    get:
      tags:
      - Inboxes
      summary: List messages for an inbox by inbox_id
      description: Returns the inbox's messages as agent messages. The holder of the inbox's read_token sees extracted codes in full. Any other token returns 403 NOT_OWNER; a missing token returns 401.
      operationId: listInboxMessages
      security:
      - bearerAuth: []
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '401':
          description: Missing or unknown token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Token does not own this inbox (NOT_OWNER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/sandbox/inboxes/{alias}/messages:
    get:
      tags:
      - Inboxes
      summary: List messages for an inbox by alias
      operationId: listSandboxMessages
      security:
      - bearerAuth: []
      parameters:
      - name: alias
        in: path
        required: true
        description: Inbox alias, as returned at creation
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Return only messages newer than this message id
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '401':
          description: Missing or unknown token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Token does not own this inbox (NOT_OWNER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/sandbox/inboxes/{alias}/messages/{id}:
    get:
      tags:
      - Inboxes
      summary: Get one message
      operationId: getSandboxMessage
      security:
      - bearerAuth: []
      parameters:
      - name: alias
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentMessage'
        '401':
          description: Missing or unknown token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Token does not own this inbox (NOT_OWNER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/sandbox/inboxes/{alias}/wait:
    get:
      tags:
      - Inboxes
      summary: Long-poll for the first message with a code or link
      description: Waits for a message newer than `after` that contains an extracted verification code or magic link. The timeout is clamped to 1-55 seconds (default 30). The wait stops early if the client disconnects.
      operationId: waitForCode
      security:
      - bearerAuth: []
      parameters:
      - name: alias
        in: path
        required: true
        schema:
          type: string
      - name: timeout
        in: query
        required: false
        description: Seconds to wait, 1-55
        schema:
          type: integer
          minimum: 1
          maximum: 55
          default: 30
      - name: after
        in: query
        required: false
        description: Only consider messages newer than this message id
        schema:
          type: string
      responses:
        '200':
          description: A message with a code or link, or a timeout marker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitResult'
        '401':
          description: Missing or unknown token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Token does not own this inbox (NOT_OWNER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/sandbox/inboxes/{alias}:
    delete:
      tags:
      - Inboxes
      summary: Delete an inbox
      description: Disables the inbox so it stops accepting mail.
      operationId: deleteSandboxInbox
      security:
      - bearerAuth: []
      parameters:
      - name: alias
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                properties:
                  success:
                    const: true
        '401':
          description: Missing or unknown token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Token does not own this inbox (NOT_OWNER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RateLimitError:
      type: object
      required:
      - error
      - code
      - message
      - retryable
      - retry_after_seconds
      properties:
        error:
          const: true
        code:
          const: RATE_LIMITED
        message:
          type: string
        retryable:
          const: true
        retry_after_seconds:
          type: integer
          examples:
          - 10
        request_id:
          type: string
    MessageList:
      type: object
      required:
      - success
      - inbox_id
      - address
      - untrusted
      - marker
      - messages
      - count
      properties:
        success:
          const: true
        inbox_id:
          type: string
        address:
          type: string
          format: email
        untrusted:
          const: true
        marker:
          const: UNTRUSTED EXTERNAL EMAIL
        messages:
          type: array
          items:
            $ref: '#/components/schemas/AgentMessage'
        count:
          type: integer
    AgentMessage:
      type: object
      required:
      - id
      - received_at
      - codes
      - links
      - untrusted
      - marker
      properties:
        id:
          type: string
        received_at:
          type: string
          format: date-time
        from:
          type:
          - string
          - 'null'
          format: email
          description: Sender address.
        from_name:
          type:
          - string
          - 'null'
          description: Sender display name. Untrusted.
        subject:
          type:
          - string
          - 'null'
          description: Subject line. Untrusted.
        codes:
          type: array
          items:
            type: string
          description: Extracted verification codes, in full, for the read_token holder.
        links:
          type: array
          items:
            type: string
            format: uri
          description: Extracted links (magic links first). Untrusted.
        text:
          type: string
          maxLength: 4000
          description: Plain-text body, truncated to 4000 characters.
        auth:
          type: object
          properties:
            verdict:
              type: string
              examples:
              - pass
            spf:
              type: string
              examples:
              - pass
            dkim:
              type: string
              examples:
              - pass
            dmarc:
              type: string
              examples:
              - pass
        untrusted:
          const: true
        marker:
          const: UNTRUSTED EXTERNAL EMAIL
    Identity:
      type: object
      required:
      - did
      - public_key
      - fingerprint
      properties:
        did:
          type: string
          description: did:key identifier for the Ed25519 public key (multicodec ed25519-pub, base58btc).
          examples:
          - did:key:z6Mk...
        public_key:
          type: string
          description: base64url of the 32-byte raw Ed25519 public key.
        fingerprint:
          type: string
          description: First 16 hex characters of SHA-256 over the raw public key.
          examples:
          - 9f2c4b1d0a7e5566
        private_key:
          type: string
          description: base64url of the PKCS8 DER private key. Returned once at creation and never stored by GetCourier.
    WaitResult:
      type: object
      required:
      - message
      properties:
        message:
          oneOf:
          - $ref: '#/components/schemas/AgentMessage'
          - type: 'null'
          description: The first new message with a code or link, or null on timeout.
        code:
          type:
          - string
          - 'null'
          description: First extracted verification code, or null.
        link:
          type:
          - string
          - 'null'
          description: First extracted link, or null.
        timeout:
          type: boolean
          description: True when no qualifying message arrived before the timeout.
    Error:
      type: object
      required:
      - error
      - code
      - message
      - retryable
      properties:
        error:
          const: true
        code:
          type: string
          examples:
          - FREE_QUOTA_EXCEEDED
          - INSUFFICIENT_CREDITS
          - PAYMENT_REQUIRED
          - ALIAS_RESERVED
          - RAIL_DISABLED
          - UNAUTHORIZED
          - NOT_OWNER
        message:
          type: string
        retryable:
          type: boolean
        hint:
          type:
          - string
          - 'null'
        retry_after_seconds:
          type: integer
        request_id:
          type: string
        payment:
          $ref: '#/components/schemas/Payment'
          description: Present on HTTP 402 responses.
    InboxCreated:
      type: object
      required:
      - success
      - address
      - inbox_id
      - read_token
      - expires_at
      - ttl_hours
      - paid
      - identity
      - alias
      - links
      properties:
        success:
          const: true
        address:
          type: string
          format: email
          examples:
          - my-agent-k3xmqz@getcourier.dev
        inbox_id:
          type: string
          examples:
          - my-agent-k3xmqz
        read_token:
          type: string
          description: Inbox-scoped bearer token, shown once.
        expires_at:
          type: string
          format: date-time
        ttl_hours:
          type: integer
        paid:
          type: boolean
        charged_credits:
          type: integer
          description: Credits charged. Present only for paid creations.
        balance:
          type: integer
          description: Remaining credit balance. Present only for paid creations.
        identity:
          $ref: '#/components/schemas/Identity'
        alias:
          type: object
          required:
          - alias
          - inbox_id
          - read_token
          - created_at
          - expires_at
          properties:
            alias:
              type: string
              format: email
            inbox_id:
              type: string
            read_token:
              type: string
            created_at:
              type: string
              format: date-time
            expires_at:
              type: string
              format: date-time
        links:
          type: object
          required:
          - messages
          - wait
          - mcp
          properties:
            messages:
              type: string
            wait:
              type: string
            mcp:
              type: string
              const: /mcp
        note:
          type: string
          examples:
          - read_token and identity.private_key are shown once
    Payment:
      type: object
      required:
      - pricing
      - steps
      properties:
        pricing:
          type: string
          examples:
          - https://getcourier.dev/v1/pricing
        steps:
          type: array
          items:
            type: string
          examples:
          - - POST /v1/accounts
            - POST /v1/deposits
            - 'retry with Authorization: Bearer <account_key>'
    CreateInboxRequest:
      type: object
      additionalProperties: false
      properties:
        purpose:
          type: string
          maxLength: 200
          description: Why the inbox exists. Stored with the inbox metadata.
          examples:
          - create an account on an API dashboard
        agent:
          type: string
          maxLength: 100
          examples:
          - build-bot-7
        service:
          type: string
          maxLength: 100
          examples:
          - generic
        alias:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,30}$
          description: Requested local-part prefix. A 6-character random suffix is always appended. Reserved names return 400 ALIAS_RESERVED.
          examples:
          - my-agent
        ttl_hours:
          type: integer
          enum:
          - 72
          - 720
          default: 72
          description: 72 hours is free; 720 hours (30 days) requires an account_key.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Either the inbox-scoped read_token returned at inbox creation, or an account_key (cak_...) returned by POST /v1/accounts. Sent as `Authorization: Bearer <token>`; never accepted in the query string.'