Inboxy Addresses API

openapi: 3.2.0
info:
  title: inboxy Addresses API
  version: 0.3.0
  summary: Read + manage your inboxy.net inbox programmatically.
  description: 'REST surface over the inboxy alias inbox. Mint aliases, list/search/read

    messages, fetch attachments, manage your API keys, and emit user-initiated

    mail under one of your aliases.


    Mail-emitting paths (`POST /v1/messages/{id}/reply`, `POST /v1/mail/send`,

    `POST /v1/mail/invite`) are recipient-locked and alias-locked server-side:

    the `From:` is always one of the caller''s `@inboxy.net` aliases, the

    recipient is validated against per-user caps and the abuse rules in

    `packages/reply`, and every external message carries the mandatory

    inboxy attribution footer. There is no arbitrary-`From:` send path.


    All endpoints require a bearer API key created from the inboxy.net web UI

    at `/account/keys` (mint is gated by step-up and lives only on the web — there

    is no API-channel mint). Pass it as `Authorization: Bearer ik_…`.


    The signed-token attachment download URLs (`/v1/attachments/{token}/download`,

    `/v1/messages/raw/{token}/download`) are public-by-token — they intentionally

    bypass bearer auth and are not listed here. Obtain them via the JSON

    endpoints below.'
  contact:
    name: inboxy
    url: https://inboxy.net
  license:
    name: Proprietary
servers:
- url: https://api.inboxy.net
  description: Production
security:
- bearerAuth: []
tags:
- name: Addresses
  description: Mint and retire @inboxy.net aliases.
paths:
  /v1/addresses:
    get:
      tags:
      - Addresses
      summary: List your aliases
      parameters:
      - name: include_retired
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Aliases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  addresses:
                    type: array
                    items:
                      $ref: '#/components/schemas/Address'
      operationId: getV1Addresses
      x-operation-id-source: derived
    post:
      tags:
      - Addresses
      summary: Mint a new alias
      description: 'Requires `manage` scope. `type` picks the shape: `standard` (default, `adjective-noun-NN`), `agent` (`agent-xxxxxxxx`, flagged `kind: agent`) or `domain` (`yourdomain.com-xxxxxxxx`, flagged `kind: agent`, needs `domain_id` or `domain` naming one of your verified domains — `invalid_domain`, 400 otherwise). Standard aliases are gated by the open-address count cap (`cap_reached`, 403, body carries `used`/`limit`) and the Early-Adopter rotation cooldown (`rotation_cooldown`, 429, body carries `retry_after_sec`/`next_allowed_at`). `agent` and `domain` aliases share a separate agent allowance (`cap_reached`, 403, `pool: "agent"`) and skip the cooldown.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressCreate'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: postV1Addresses
      x-operation-id-source: derived
  /v1/addresses/{id}:
    delete:
      tags:
      - Addresses
      summary: Retire an alias
      description: Requires `manage` scope. Stops accepting new mail; existing messages remain visible.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Retired.
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteV1AddressesById
      x-operation-id-source: derived
  /v1/addresses/{id}/attribution:
    post:
      tags:
      - Addresses
      summary: Record where an alias was used (browser-extension flow)
      description: Accepts either `manage` or the narrow `extension` scope. Idempotent on `(address_id, site_origin)` — re-recording bumps `last_used_at` and returns `200`; the first record returns `201`. Address-scoped keys can only attribute the alias they're bound to. Writes an `audit_log` row with action `api_address_attribution`.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressAttributionRequest'
      responses:
        '200':
          description: Attribution updated (existing row).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressAttribution'
        '201':
          description: Attribution recorded (new row).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressAttribution'
        '400':
          description: '`invalid_origin` — body missing or origin malformed.'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postV1AddressesByIdAttribution
      x-operation-id-source: derived
components:
  schemas:
    AddressAttributionRequest:
      type: object
      required:
      - site_origin
      properties:
        site_origin:
          type: string
          description: Scheme + host where the alias was used. Origin-validated server-side.
        site_label:
          type: string
          description: Optional human label (e.g. site title); sanitised + truncated.
    AddressCreate:
      type: object
      properties:
        label:
          type: string
          maxLength: 64
          description: Optional user-facing label.
        scheme:
          type: string
          enum:
          - adjective-noun
          - opaque
          default: adjective-noun
          description: Generation scheme for `standard` aliases. `adjective-noun` → e.g. brisk-otter-42; `opaque` → random.
        type:
          type: string
          enum:
          - standard
          - agent
          - domain
          default: standard
          description: '`agent` → agent-xxxxxxxx; `domain` → yourdomain.com-xxxxxxxx (requires `domain_id`). Both are flagged `kind: agent`.'
        domain_id:
          type: string
          format: uuid
          description: A verified domain's id (from `GET /v1/domains`). Required (or `domain`) when `type` is `domain`.
        domain:
          type: string
          description: 'Alternative to `domain_id`: the verified domain''s hostname, e.g. `nike.com`.'
    AddressAttribution:
      type: object
      required:
      - id
      - address_id
      - site_origin
      - source
      - first_used_at
      - last_used_at
      properties:
        id:
          type: string
          format: uuid
        address_id:
          type: string
          format: uuid
        site_origin:
          type: string
          description: Scheme + host, e.g. `https://example.com`.
        site_label:
          type:
          - string
          - 'null'
        source:
          type: string
          enum:
          - extension
        first_used_at:
          type: integer
          description: Unix seconds.
        last_used_at:
          type: integer
          description: Unix seconds.
    Address:
      type: object
      required:
      - id
      - local_part
      - full_address
      - status
      - created_at
      properties:
        id:
          type: string
          format: uuid
        local_part:
          type: string
        full_address:
          type: string
          format: email
        label:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - active
          - retired
        kind:
          type: string
          enum:
          - standard
          - agent
          description: '`agent` aliases draw from the separate agent allowance.'
        created_at:
          type: integer
        retired_at:
          type:
          - integer
          - 'null'
        total:
          type: integer
          minimum: 0
          description: Total messages ever received at this alias (list-view only).
        unread:
          type: integer
          minimum: 0
          description: Unread messages currently on this alias (list-view only).
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - gone
          - rate_limited
          - internal
          - invalid_token
          - blocked
        message:
          type: string
  responses:
    NotFound:
      description: No matching resource owned by the caller.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Token lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ik_…
      description: Static API key. Three scopes — `read` (everything except mutations), `manage` (mutations other than sending) and `send` (`/v1/mail/send`, replies, invites). Mint at https://inboxy.net/account/keys (the web UI gates mint with step-up; there is no API-channel mint).