Inboxy Outbox API

openapi: 3.2.0
info:
  title: inboxy Outbox 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: Outbox
  description: Logged outbound queue — what you or your agent sent.
paths:
  /v1/outbox:
    get:
      tags:
      - Outbox
      summary: List sent replies
      description: Newest first. Use `before` (ISO-8601) to paginate by send time. Filter by `status` / `kind` / `in_reply_to` for scoped listings.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: before
        in: query
        schema:
          type: string
          format: date-time
      - name: status
        in: query
        schema:
          type: string
          enum:
          - queued
          - sent
          - failed
          - rejected
          - suppressed
      - name: kind
        in: query
        schema:
          type: string
          enum:
          - reply
          - forward
          - digest
      - name: in_reply_to
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of outbox rows (body fields elided).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboxList'
      operationId: getV1Outbox
      x-operation-id-source: derived
  /v1/outbox/count:
    get:
      tags:
      - Outbox
      summary: Count sent replies matching the filter
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - queued
          - sent
          - failed
          - rejected
          - suppressed
      - name: kind
        in: query
        schema:
          type: string
          enum:
          - reply
          - forward
          - digest
      responses:
        '200':
          description: Total.
          content:
            application/json:
              schema:
                type: object
                required:
                - total
                properties:
                  total:
                    type: integer
                    minimum: 0
      operationId: getV1OutboxCount
      x-operation-id-source: derived
  /v1/outbox/{id}:
    get:
      tags:
      - Outbox
      summary: Get one sent reply, including body_text + body_html
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Outbox row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboxMessage'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1OutboxById
      x-operation-id-source: derived
    delete:
      tags:
      - Outbox
      summary: Permanently delete a sent reply. Kept rows must be unkept 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: Row is currently kept — unkeep first.
      operationId: deleteV1OutboxById
      x-operation-id-source: derived
components:
  schemas:
    OutboxMessage:
      type: object
      required:
      - id
      - kind
      - to_email
      - from_email
      - status
      - sent_at
      description: 'One sent reply. `status` reflects the send pipeline: queued (in-flight) → sent / rejected / suppressed. `body_text` + `body_html` are populated on /v1/outbox/{id} but elided from list rows.'
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - reply
          - forward
          - digest
        in_reply_to_message_id:
          type:
          - string
          - 'null'
          format: uuid
        to_email:
          type: string
          format: email
        from_email:
          type: string
          format: email
        subject:
          type:
          - string
          - 'null'
        body_text:
          type: string
          description: Plain-text body, only on /v1/outbox/{id}.
        body_html:
          type:
          - string
          - 'null'
        message_id_rfc5322:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - queued
          - sent
          - failed
          - rejected
          - suppressed
        status_reason:
          type:
          - string
          - 'null'
        sent_at:
          type: integer
          description: Unix seconds — when the row was enqueued.
        delivered_at:
          type:
          - integer
          - 'null'
          description: Unix seconds — when the sender flipped to 'sent'.
        kept_at:
          type:
          - integer
          - 'null'
    OutboxList:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/OutboxMessage'
    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'
    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).