Inboxy Messages API

openapi: 3.2.0
info:
  title: inboxy Messages 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: Messages
  description: List, read, search, mark, delete.
paths:
  /v1/messages:
    get:
      tags:
      - Messages
      summary: List messages, newest first
      parameters:
      - name: address_id
        in: query
        schema:
          type: string
          format: uuid
      - name: classification
        in: query
        schema:
          $ref: '#/components/schemas/Classification'
      - name: read
        in: query
        schema:
          type: boolean
      - name: since
        in: query
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: cursor
        in: query
        schema:
          type: string
        description: Opaque cursor from a previous `next_cursor`.
      responses:
        '200':
          description: Page of messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessagesPage'
      operationId: getV1Messages
      x-operation-id-source: derived
  /v1/messages/count:
    get:
      tags:
      - Messages
      summary: Count messages matching a filter
      description: Same filter parameters as `/v1/messages`. Returns `{ total, unread }`; useful for a badge or pagination decision without walking the cursor.
      parameters:
      - name: address_id
        in: query
        schema:
          type: string
          format: uuid
      - name: classification
        in: query
        schema:
          $ref: '#/components/schemas/Classification'
      - name: read
        in: query
        schema:
          type: boolean
      - name: since
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Aggregate counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResult'
      operationId: getV1MessagesCount
      x-operation-id-source: derived
  /v1/messages/{id}:
    get:
      tags:
      - Messages
      summary: 'Get one message: metadata, parsed text body, headers, attachments, image refs'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDetail'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1MessagesById
      x-operation-id-source: derived
    delete:
      tags:
      - Messages
      summary: Permanently delete a message (cascade attachments + embedding)
      description: Requires `manage` scope. Irreversible. Refuses with 409 `kept_must_unkeep_first` if the message has `kept_at` set — call `/v1/messages/{id}/unkeep` first.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: '`kept_must_unkeep_first` — unkeep before deleting.'
      operationId: deleteV1MessagesById
      x-operation-id-source: derived
  /v1/messages/{id}/images:
    get:
      tags:
      - Messages
      summary: Detailed image refs for one message
      description: 'Returns per-image `width`/`height` hints and (for inline cid: images) the matching `attachment_id`. Original third-party URLs never leave the worker — only signed `proxy_url`s.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Image refs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  images:
                    type: array
                    items:
                      $ref: '#/components/schemas/ImageRef'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1MessagesByIdImages
      x-operation-id-source: derived
  /v1/messages/{id}/raw:
    get:
      tags:
      - Messages
      summary: Issue a signed download URL for the raw RFC822 .eml
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Signed URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedUrl'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          description: Body purged/lost.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1MessagesByIdRaw
      x-operation-id-source: derived
  /v1/messages/{id}/read:
    post:
      tags:
      - Messages
      summary: Mark a message as read
      description: Requires `manage` scope.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  read:
                    type: boolean
                    enum:
                    - true
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postV1MessagesByIdRead
      x-operation-id-source: derived
  /v1/messages/{id}/unread:
    post:
      tags:
      - Messages
      summary: Mark a message as unread
      description: Requires `manage` scope.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  read:
                    type: boolean
                    enum:
                    - false
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postV1MessagesByIdUnread
      x-operation-id-source: derived
  /v1/messages/read-all:
    post:
      tags:
      - Messages
      summary: Mark every unread message matching a filter as read
      description: 'Requires `manage` scope. Body is an optional filter — `address_id`, `classification`, and/or `before` (ISO-8601, only messages received strictly before this instant). Empty body marks every unread message read. Idempotent: re-running returns `{ marked: 0 }` once the set is empty.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkAllMessagesRequest'
      responses:
        '200':
          description: Update succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkAllResult'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: postV1MessagesReadAll
      x-operation-id-source: derived
  /v1/messages/{id}/reply:
    post:
      tags:
      - Messages
      summary: Send a reply to the ORIGINAL SENDER of a stored message
      description: 'Requires `send` scope. Recipient is locked server-side to `messages.from_email`; the From header is `@inboxy.net` (alias the original was delivered to). Body cap: 2000 chars. Refused on spam-classified messages, messages older than 30 days, or when the per-user reply rate cap is hit (5/hour, 20/day, 1 per 60s). Every reply writes an `audit_log` row with the SHA-256 of the recipient. Optional `attachment_ids[]` references prior `POST /v1/outbox-attachments` uploads (up to 5 files, 20 MB each, 20 MB total).'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplyRequest'
      responses:
        '200':
          description: Reply queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplyResult'
        '400':
          description: Validation failure (spam_blocked, stale_message, body_too_long, …).
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          description: Alias for this message no longer exists.
        '429':
          description: Rate limit hit. Body includes `scope` + `retry_after_sec`.
      operationId: postV1MessagesByIdReply
      x-operation-id-source: derived
  /v1/messages/{id}/keep:
    post:
      tags:
      - Messages
      summary: Pin a message so the retention sweep won't delete it
      description: Cap of 10 currently-kept per user. Idempotent — re-keeping returns the existing `kept_at`. Writes an `audit_log` row with action `api_message_kept`.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Kept (or already-kept).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeepResult'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: '`keep_limit_reached` — cap depends on your plan. Unkeep one to free a slot.'
      operationId: postV1MessagesByIdKeep
      x-operation-id-source: derived
  /v1/messages/{id}/unkeep:
    post:
      tags:
      - Messages
      summary: Remove the retention pin from a message
      description: 'Idempotent. Returns `{ id, kept_at: null }` whether or not the message was previously kept.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Unkept (or already-unkept).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeepResult'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postV1MessagesByIdUnkeep
      x-operation-id-source: derived
  /v1/messages/{id}/unsubscribe:
    get:
      tags:
      - Messages
      summary: Surface unsubscribe methods for a message
      description: 'Parses the `List-Unsubscribe` header (RFC 2369 — mailto + URLs), the `List-Unsubscribe-Post: List-Unsubscribe=One-Click` flag (RFC 8058), and body `` links whose anchor text or URL path matches `/unsubscribe|opt-out/i`. **Read-only** — the server does NOT visit or POST the URL. The caller decides what to do with `recommended` (one_click_post is the only auto-safe option; mailto goes through the user''s normal sender path; generic http links must be opened by hand).'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Parsed unsubscribe info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsubscribeInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          description: Body lost, purged, or unparseable.
      operationId: getV1MessagesByIdUnsubscribe
      x-operation-id-source: derived
  /v1/read-all:
    post:
      tags:
      - Messages
      summary: Mark every unread mail AND every unread article read in one call
      description: Requires `manage` scope. Optional `before` (ISO-8601) scopes to items received/published strictly before that instant. Returns `{ mail_marked, articles_marked }`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkAllCombinedRequest'
      responses:
        '200':
          description: Update succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkAllCombinedResult'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: postV1ReadAll
      x-operation-id-source: derived
  /v1/messages/search:
    post:
      tags:
      - Messages
      summary: Semantic search across your inbox
      description: Embeds the query with the same model the classifier writes with, then runs a vector query against your messages. `user_id` filter is mandatory and applied server-side — you cannot omit or override it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Ranked matches.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: postV1MessagesSearch
      x-operation-id-source: derived
components:
  schemas:
    Classification:
      type: string
      enum:
      - otp
      - login_link
      - verify
      - receipt
      - notice
      - marketing
      - spam
      - other
    SearchRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 1000
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
        filters:
          type: object
          properties:
            address_id:
              type: string
              format: uuid
            classification:
              $ref: '#/components/schemas/Classification'
            from_domain:
              type: string
            since:
              type: string
              format: date-time
    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
    MessagesPage:
      type: object
      required:
      - messages
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageMeta'
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass to `?cursor=` for the next page.
    UnsubMethod:
      oneOf:
      - type: object
        required:
        - kind
        - url
        - source
        properties:
          kind:
            type: string
            enum:
            - one_click_post
          url:
            type: string
            format: uri
          source:
            type: string
            enum:
            - header
      - type: object
        required:
        - kind
        - url
        - source
        properties:
          kind:
            type: string
            enum:
            - http
          url:
            type: string
            format: uri
          source:
            type: string
            enum:
            - header
            - body
          text:
            type:
            - string
            - 'null'
      - type: object
        required:
        - kind
        - url
        - to
        - subject
        - source
        properties:
          kind:
            type: string
            enum:
            - mailto
          url:
            type: string
          to:
            type: string
            format: email
          subject:
            type:
            - string
            - 'null'
          source:
            type: string
            enum:
            - header
    MarkAllMessagesRequest:
      type: object
      description: Optional filter scoping which messages are marked. Empty object marks every unread message read.
      properties:
        address_id:
          type: string
          format: uuid
        classification:
          $ref: '#/components/schemas/Classification'
        before:
          type: string
          format: date-time
          description: ISO-8601; only mark messages received strictly before this instant.
    KeepResult:
      type: object
      required:
      - id
      - kept_at
      description: Result of a keep / unkeep call. `kept_at` is null after unkeep, unix-seconds after keep.
      properties:
        id:
          type: string
          format: uuid
        kept_at:
          type:
          - integer
          - 'null'
    ReplyResult:
      type: object
      required:
      - id
      - replied
      - to
      - from
      - subject
      - idempotency_key
      properties:
        id:
          type: string
          format: uuid
        replied:
          type: boolean
        to:
          type: string
          format: email
        from:
          type: string
          format: email
        subject:
          type: string
        idempotency_key:
          type: string
        attachments:
          type: array
          items:
            type: object
            properties:
              r2_key:
                type: string
              filename:
                type:
                - string
                - 'null'
              content_type:
                type: string
              size_bytes:
                type: integer
    ImageRef:
      type: object
      required:
      - kind
      - proxy_url
      properties:
        kind:
          type: string
          enum:
          - external
          - inline
        proxy_url:
          type: string
          format: uri
          description: Short-lived l.inboxy.net/img/{token} URL. Original third-party URLs never leave the worker.
        alt:
          type:
          - string
          - 'null'
        width:
          type:
          - string
          - 'null'
        height:
          type:
          - string
          - 'null'
        attachment_id:
          type: string
          description: Inline-only.
    Attachment:
      type: object
      required:
      - id
      - content_type
      - size_bytes
      properties:
        id:
          type: string
          format: uuid
        filename:
          type:
          - string
          - 'null'
        content_type:
          type:
          - string
          - 'null'
        size_bytes:
          type: integer
    SearchResult:
      allOf:
      - $ref: '#/components/schemas/MessageMeta'
      - type: object
        required:
        - score
        properties:
          score:
            type: number
            description: Cosine similarity, 0..1.
    MarkAllCombinedResult:
      type: object
      required:
      - mail_marked
      - articles_marked
      description: Counts from /v1/read-all — rows actually changed in each domain.
      properties:
        mail_marked:
          type: integer
          minimum: 0
        articles_marked:
          type: integer
          minimum: 0
    MessageDetail:
      allOf:
      - $ref: '#/components/schemas/MessageMeta'
      - type: object
        properties:
          envelope_from:
            type:
            - string
            - 'null'
          text_body:
            type:
            - string
            - 'null'
          headers:
            type:
            - object
            - 'null'
            additionalProperties: true
          attachments:
            type: array
            items:
              $ref: '#/components/schemas/Attachment'
          images:
            type: array
            items:
              $ref: '#/components/schemas/ImageRef'
    MarkAllResult:
      type: object
      required:
      - marked
      description: Result of a bulk mark-as-read. `marked` is the number of rows mutated by this call (already-read rows are skipped).
      properties:
        marked:
          type: integer
          minimum: 0
    MessageMeta:
      type: object
      required:
      - id
      - from_email
      - received_at
      - read
      properties:
        id:
          type: string
          format: uuid
        address_id:
          type: string
          format: uuid
        from_email:
          type: string
          format: email
        from_label:
          type:
          - string
          - 'null'
        subject:
          type:
          - string
          - 'null'
        received_at:
          type: integer
          description: Unix seconds.
        classification:
          $ref: '#/components/schemas/Classification'
        urgency:
          type:
          - string
          - 'null'
          enum:
          - low
          - normal
          - high
          - null
        summary:
          type:
          - string
          - 'null'
        confidence:
          type:
          - number
          - 'null'
        read:
          type: boolean
        pending_classification:
          type: boolean
        forwarded_at:
          type:
          - integer
          - 'null'
        body_lost:
          type: boolean
        kept_at:
          type:
          - integer
          - 'null'
          description: Unix seconds when the user pinned this message to bypass the retention sweep. Null = not kept.
    SignedUrl:
      type: object
      required:
      - url
      - expires_at
      properties:
        url:
          type: string
          format: uri
        expires_at:
          type: integer
          description: Unix seconds.
        filename:
          type:
          - string
          - 'null'
        content_type:
          type:
          - string
          - 'null'
        size_bytes:
          type: integer
    MarkAllCombinedRequest:
      type: object
      description: Optional filter for the combined zero-everything tool. Empty object zeroes all unread.
      properties:
        before:
          type: string
          format: date-time
          description: ISO-8601; only mark items received/published strictly before this instant.
    UnsubscribeInfo:
      type: object
      required:
      - id
      - from
      - subject
      - methods
      - recommended
      description: 'Unsubscribe methods parsed from a message. `recommended` is the first by preference: one_click_post (RFC 8058) → mailto → http link.'
      properties:
        id:
          type: string
          format: uuid
        from:
          type:
          - string
          - 'null'
        subject:
          type:
          - string
          - 'null'
        methods:
          type: array
          items:
            $ref: '#/components/schemas/UnsubMethod'
        recommended:
          anyOf:
          - $ref: '#/components/schemas/UnsubMethod'
          - type: 'null'
    CountResult:
      type: object
      required:
      - total
      - unread
      description: Aggregate over a filtered set. `total` counts every matching row; `unread` is the subset that is still unread.
      properties:
        total:
          type: integer
          minimum: 0
        unread:
          type: integer
          minimum: 0
    ReplyRequest:
      type: object
      required:
      - body_text
      description: Reply body. The server appends a `--` separator + quoted-original block; callers cannot suppress it.
      properties:
        body_text:
          type: string
          minLength: 1
          maxLength: 2000
          description: Plain-text body. Capped at 2000 chars.
        body_html:
          type: string
          description: Optional HTML body. Visible-text length capped server-side at 2000 chars.
        attachment_ids:
          type: array
          items:
            type: string
            format: uuid
          maxItems: 5
          description: Ids returned by `POST /v1/outbox-attachments`. Each may be used at most once. Per-file cap 20 MB, total cap 20 MB.
  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).