Nuvidian AI, LLC Sandbox API

openapi: 3.2.0
info:
  title: GetCourier Sandbox 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: Sandbox
paths:
  /v1/sandbox/inboxes/{alias}/send:
    post:
      operationId: sendMessage
      summary: Send email from the inbox's own address
      description: 'Free inboxes can reply to anyone who emailed them, up to 100 sends a month. Free sending is reply-only because spam bots abuse free email senders. To send to anyone, deposit credits (20 credits = US$0.002 per recipient) or verify a human owner email to use the free 100 on anyone. Limits: 50 recipients per inbox per UTC day, 200 per account per day in the first 7 days, 50 per message. Own domains: verify a domain you own (POST /v1/sandbox/domains, MCP add_domain) and create inboxes on it; own-domain sending is paid (20 credits per recipient), 100 recipients per inbox per day for the domain''s first 7 days, then 500; up to 5 domains per account.'
      parameters:
      - name: alias
        in: path
        required: true
        schema:
          type: string
      - name: X-Account-Key
        in: header
        required: false
        schema:
          type: string
        description: account_key to pay from (credits)
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - to
              - subject
              properties:
                to:
                  type: array
                  items:
                    type: string
                    format: email
                cc:
                  type: array
                  items:
                    type: string
                    format: email
                subject:
                  type: string
                text:
                  type: string
                html:
                  type: string
                reply_to:
                  type: string
                  format: email
                in_reply_to:
                  type: string
                  description: <message-id> being replied to
      responses:
        '202':
          description: Sent
        '402':
          description: FREE_SEND_LIMIT or INSUFFICIENT_CREDITS or REPLY_ONLY (with unlock options)
        '403':
          description: REPLY_ONLY, SUSPENDED or FROM_NOT_ALLOWED
        '429':
          description: DAILY_CAP or NEW_ACCOUNT_CAP
        '503':
          description: SENDING_PAUSED
      tags:
      - Sandbox
  /v1/sandbox/owner/verify:
    post:
      operationId: verifyOwner
      summary: Email a confirmation link to a human owner; once confirmed, the account's free…
      responses:
        '200':
          description: Verification email sent
        '409':
          description: OWNER_EMAIL_TAKEN or ALREADY_VERIFIED
        '429':
          description: VERIFY_RATE_LIMITED
      tags:
      - Sandbox
  /v1/sandbox/domains:
    post:
      operationId: addDomain
      summary: Register a domain you own for sending and receiving
      description: 'Own domains: verify a domain you own (POST /v1/sandbox/domains, MCP add_domain) and create inboxes on it; own-domain sending is paid (20 credits per recipient), 100 recipients per inbox per day for the domain''s first 7 days, then 500; up to 5 domains per account. The response lists the DNS records to publish: 3 DKIM CNAMEs, a MAIL FROM MX and SPF TXT on bounce., a DMARC TXT, and the inbound MX (mail.getcourier.dev).'
      parameters:
      - name: X-Account-Key
        in: header
        required: true
        schema:
          type: string
        description: account_key (an account with credits)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              properties:
                domain:
                  type: string
                  example: example.com
      responses:
        '201':
          description: Registered; publish the returned DNS records (dns), then poll GET /v1/sandbox/domains/{domain}
        '400':
          description: INVALID_DOMAIN
        '401':
          description: ACCOUNT_REQUIRED
        '402':
          description: PAID_ACCOUNT_REQUIRED (account needs credits)
        '403':
          description: DOMAIN_RESERVED
        '409':
          description: DOMAIN_TAKEN, DOMAIN_UNAVAILABLE or DOMAIN_LIMIT (5 per account)
        '502':
          description: PROVIDER_ERROR
      tags:
      - Sandbox
    get:
      operationId: listDomains
      summary: List your registered domains
      parameters:
      - name: X-Account-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ domains: [...] }'
      tags:
      - Sandbox
  /v1/sandbox/domains/{domain}:
    get:
      operationId: domainStatus
      summary: Verification status (DKIM and MAIL FROM)
      parameters:
      - name: X-Account-Key
        in: header
        required: true
        schema:
          type: string
        description: account_key (an account with credits)
      - name: domain
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status and DNS records
        '404':
          description: DOMAIN_NOT_FOUND
      tags:
      - Sandbox
    delete:
      operationId: removeDomain
      summary: Remove a domain you registered
      parameters:
      - name: X-Account-Key
        in: header
        required: true
        schema:
          type: string
        description: account_key (an account with credits)
      - name: domain
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Removed
        '404':
          description: DOMAIN_NOT_FOUND
      tags:
      - Sandbox
  /v1/sandbox/domains/{domain}/inboxes:
    post:
      operationId: createDomainInbox
      summary: Create an inbox on a verified domain (30-day paid inbox, 2000 credits)
      parameters:
      - name: X-Account-Key
        in: header
        required: true
        schema:
          type: string
        description: account_key (an account with credits)
      - name: domain
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - local_part
              properties:
                local_part:
                  type: string
                  example: support
      responses:
        '201':
          description: Inbox created; returns address and read_token
        '400':
          description: INVALID_LOCAL_PART
        '404':
          description: DOMAIN_NOT_FOUND
        '409':
          description: DOMAIN_NOT_VERIFIED or ADDRESS_TAKEN
      tags:
      - Sandbox
components:
  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.'