Inboxy Domains API

openapi: 3.2.0
info:
  title: inboxy Domains 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: Domains
  description: Verify a custom domain for a future sending feature (1 on free and standard, 10 on pro). Verification only — a verified domain cannot yet be used to send mail.
paths:
  /v1/domains:
    get:
      tags:
      - Domains
      summary: List your verified sending domains
      description: Verification only — a verified domain cannot yet be used to send mail. Unlike a webhook's signing secret, `dns_records.txt.value` is not a secret and is included on every response, not just at creation.
      responses:
        '200':
          description: Domains.
          content:
            application/json:
              schema:
                type: object
                properties:
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/VerifiedDomain'
      operationId: getV1Domains
      x-operation-id-source: derived
    post:
      tags:
      - Domains
      summary: Register a domain for verification
      description: Requires `manage` scope. Gated by the plan's `verified_domain_limit` (`cap_reached`, 403, body carries `used`/`limit`). `domain` is validated as a bare hostname (`invalid_domain`, 400); a domain already claimed by any inboxy account is rejected as a conflict (`already_claimed`, 409 — a deliberate divergence from most other create endpoints' single 400 reason, since this is a conflict with existing state rather than a malformed request). The response's `dns_records` are the TXT/SPF/DKIM records to publish; verification runs on a periodic sweep or on-demand via `POST /v1/domains/{id}/verify`. Verification only — a verified domain cannot yet be used to send mail.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifiedDomainCreate'
      responses:
        '201':
          description: Created, in `pending` status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedDomain'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: '`already_claimed` — this domain is already registered by an inboxy account.'
      operationId: postV1Domains
      x-operation-id-source: derived
  /v1/domains/{id}:
    delete:
      tags:
      - Domains
      summary: Delete a verified domain
      description: Requires `manage` scope.
      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'
      operationId: deleteV1DomainsById
      x-operation-id-source: derived
  /v1/domains/{id}/rotate-token:
    post:
      tags:
      - Domains
      summary: Rotate a domain's verification token
      description: Requires `manage` scope. The previous TXT challenge value stops being accepted immediately; publish the new value at `_inboxy-challenge.{domain}` and re-verify. Resets verification progress — a `verified` domain is demoted to `pending` until it re-earns verification with the new token.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Rotated.
          content:
            application/json:
              schema:
                type: object
                required:
                - verify_token
                properties:
                  verify_token:
                    type: string
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postV1DomainsByIdRotateToken
      x-operation-id-source: derived
  /v1/domains/{id}/verify:
    post:
      tags:
      - Domains
      summary: Run a DNS check for this domain now
      description: Requires `manage` scope. Rate-limited to 1 request per 60 s per domain id (shared with the account UI's identical action). Queries live DNS for the TXT challenge, SPF, and DKIM CNAME records and persists the result; three consecutive passing checks move the domain to `verified`, two consecutive failures after that demote it back to `verification_lost`.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Check run; current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedDomain'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limit hit — at most one verify-now check per domain per 60 s.
      operationId: postV1DomainsByIdVerify
      x-operation-id-source: derived
components:
  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'
  schemas:
    VerifiedDomain:
      type: object
      required:
      - id
      - domain
      - status
      - txt_ok
      - spf_state
      - spf_suggestion
      - dkim_cname_ok
      - last_checked_at
      - created_at
      - verified_at
      - dns_records
      properties:
        id:
          type: string
          format: uuid
        domain:
          type: string
        status:
          type: string
          enum:
          - pending
          - verified
          - verification_lost
          description: '`verified` after 3 consecutive passing checks; demoted to `verification_lost` after 2 consecutive failures once verified. Verification only — this status never grants a sending capability.'
        txt_ok:
          type: boolean
          description: Ownership TXT challenge record found and matching.
        spf_state:
          type:
          - string
          - 'null'
          enum:
          - ok
          - conflict
          - missing
          - null
        spf_suggestion:
          type:
          - string
          - 'null'
          description: Suggested SPF record text. Null iff `spf_state` is `ok`.
        dkim_cname_ok:
          type: boolean
          description: DKIM selector CNAME found and matching.
        last_checked_at:
          type:
          - integer
          - 'null'
          description: Unix seconds.
        created_at:
          type: integer
          description: Unix seconds.
        verified_at:
          type:
          - integer
          - 'null'
          description: Unix seconds of the transition into `verified`. A re-check that keeps the domain verified, or one that fails without demoting it, never clears this. It IS cleared back to null if the domain is demoted to `pending` (e.g. by rotating its verify token) — it re-marks the transition on the next fresh verification.
        dns_records:
          type: object
          required:
          - txt
          - spf
          - dkim
          description: The DNS records to publish at your registrar. `txt.value` is not a secret — it is meant to be published in public DNS, and (unlike a webhook's signing secret) is returned on every response, not just at creation.
          properties:
            txt:
              type: object
              required:
              - host
              - value
              properties:
                host:
                  type: string
                value:
                  type: string
            spf:
              type:
              - object
              - 'null'
              description: Null once `spf_state` is `ok` — nothing left to change.
              properties:
                host:
                  type: string
                value:
                  type:
                  - string
                  - 'null'
            dkim:
              type: object
              required:
              - host
              - type
              - value
              properties:
                host:
                  type: string
                type:
                  type: string
                  enum:
                  - CNAME
                value:
                  type: string
    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
    VerifiedDomainCreate:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
          description: Bare hostname, e.g. `mail.example.com`. No scheme, path, port, or IP literal.
  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).