DevInbox API

openapi: 3.1.0
info:
  title: DevInbox API
  version: '2026-11-05'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-05: 13 operation(s) read from 5 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; DevInbox has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 20
    documentation: -7
    pages-with-code: 4
    pages-read: 5
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-05'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://devinbox.io/doc/api-guide
  - https://devinbox.io/doc/developer-guide
  - https://devinbox.io/doc/integration-tests
  - https://devinbox.io/doc/ai-agents
  - https://devinbox.io/doc/templates
servers:
- url: https://api.devinbox.io
paths:
  /:
    get:
      operationId: get
      tags:
      - Api
      summary: GET /
      x-source: https://devinbox.io/doc/api-guide
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n import requests\n import time\nAPI_KEY = \"your_api_key\" \nBASE_URL = \"https://api.devinbox.io\" \nheaders = { \"X-Api-Key\"\
          \ : API_KEY}"
  /mailboxes:
    get:
      operationId: get_mailboxes
      tags:
      - Mailboxes
      summary: GET /mailboxes
      x-source: https://devinbox.io/doc/api-guide
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMailboxesResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -H \"X-Api-Key: your_api_key_here\"  https://api.devinbox.io/mailboxes \n Find your API key in your dashboard under Settings\
          \ ? API Keys \n Base URL \n https://api.devinbox.io \n Status Endpoints \n GET \n /status \n Returns OK if the API service is running\
          \ and available. This endpoint does not require authentication.\n Response 200 OK \n 200 OK \n Example "
    post:
      operationId: post_mailboxes
      tags:
      - Mailboxes
      summary: POST /mailboxes
      x-source: https://devinbox.io/doc/api-guide
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMailboxesRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMailboxesResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://api.devinbox.io/mailboxes  -H \"X-Api-Key: your_api_key_here\"  -H \"Content-Type: application/json\" \
          \ -d '{\"projectName\": \"test-project\", \"isTemporary\": true}' \n Error Responses \n • 400 - Project not found or persistent mailbox\
          \ creation attempted \n • 401 - Invalid or missing API key \n • 429 - Rate limit exceeded \n Message Endpoints \n GET \n /messages/{key}/count\
          \ \n Returns the tota"
  /messages/{key}:
    get:
      operationId: get_messages_key
      tags:
      - Messages
      summary: Retrieves messages from a mailbox with pagination support.
      x-source: https://devinbox.io/doc/api-guide
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      - name: skip
        in: query
        required: false
        schema:
          type: integer
        description: 'Number of messages to skip (default: 0)'
      - name: take
        in: query
        required: false
        schema:
          type: integer
        description: 'Number of messages to return (default: 10, max: 25)'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessagesKeyResponse'
      x-evidence:
        kind: documentation
  /messages/{key}/count:
    get:
      operationId: get_messages_key_count
      tags:
      - Messages
      summary: Returns the total number of messages in the specified mailbox.
      x-source: https://devinbox.io/doc/api-guide
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessagesKeyCountResponse'
      x-evidence:
        kind: documentation
  /messages/{key}/get:
    get:
      operationId: get_messages_key_get
      tags:
      - Messages
      summary: Retrieves a specific message from the specified mailbox using its unique ID.
      x-source: https://devinbox.io/doc/api-guide
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: The unique GUID of the message
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /messages/{key}/last:
    get:
      operationId: get_messages_key_last
      tags:
      - Messages
      summary: Returns the most recent message from the mailbox.
      x-source: https://devinbox.io/doc/api-guide
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /messages/{key}/send:
    post:
      operationId: post_messages_key_send
      tags:
      - Messages
      summary: Sends an email from the persistent inbox identified by {key}.
      x-source: https://devinbox.io/doc/api-guide
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMessagesKeySendRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /messages/{key}/single:
    get:
      operationId: get_messages_key_single
      tags:
      - Messages
      summary: Returns the message when the mailbox contains exactly one message.
      x-source: https://devinbox.io/doc/api-guide
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessagesKeySingleResponse'
      x-evidence:
        kind: documentation
  /messages/{key}/wait:
    get:
      operationId: get_messages_key_wait
      tags:
      - Messages
      summary: Long‑poll until an email arrives.
      x-source: https://devinbox.io/doc/ai-agents
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        required: true
        schema:
          type: string
        description: Your API key.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /messages/{key}/{template}/last:
    get:
      operationId: get_messages_key_template_last
      tags:
      - Messages
      summary: Returns the most recent message and parses it using the specified template.
      x-source: https://devinbox.io/doc/api-guide
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      - name: template
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /messages/{key}/{template}/single:
    get:
      operationId: get_messages_key_template_single
      tags:
      - Messages
      summary: Returns the single message and parses it using the specified template.
      x-source: https://devinbox.io/doc/api-guide
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      - name: template
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessagesKeyTemplateSingleResponse'
      x-evidence:
        kind: documentation
  /status:
    get:
      operationId: get_status
      tags:
      - Status
      summary: GET /status
      x-source: https://devinbox.io/doc/api-guide
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStatusResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://api.devinbox.io/status \n Mailbox Endpoints \n POST \n /mailboxes \n Creates a new mailbox (temporary or persistent).\
          \ Returns a unique mailbox key and password for SMTP authentication.\n Note: Persistent mailboxes can only be created via the web portal\
          \ - API only supports temporary mailboxes.\n Request Body \n {\n \"name\" : null ,\n \"projectName\" : \"my-project\" ,\n \"isTemporary\"\
          \ : true \n} \n Requ"
components:
  schemas:
    GetResponse:
      type: object
      properties:
        isTemporary:
          type: boolean
    GetMailboxesResponse:
      type: object
      properties:
        key:
          type: string
        password:
          type: string
    PostMailboxesRequest:
      type: object
      properties:
        projectName:
          type: string
        isTemporary:
          type: boolean
    PostMailboxesResponse:
      type: object
      properties:
        key:
          type: string
        count:
          type: integer
    GetMessagesKeyResponse:
      type: object
      properties:
        key:
          type: string
        count:
          type: integer
        messages:
          type: array
          description: Array of message objects
    GetMessagesKeyCountResponse:
      type: object
      properties:
        key:
          type: string
        count:
          type: integer
    PostMessagesKeySendRequest:
      type: object
      properties:
        to:
          type: array
          description: Array of recipient addresses
        cc:
          type: array
          description: Optional array of CC addresses
        bcc:
          type: array
          description: Optional array of BCC addresses
        subject:
          type: string
          description: Message subject
        text:
          type: string
          description: Message body text
        html:
          type: string
          description: Message body HTML
        inReplyTo:
          type: string
          description: Optional. The uniqueId of a message previously received in this inbox.
      required:
      - to
    GetMessagesKeySingleResponse:
      type: object
      properties:
        uniqueId:
          type: string
        from:
          type: array
        to:
          type: array
        cc:
          type: string
        bcc:
          type: string
        subject:
          type: string
        body:
          type: string
        isHtml:
          type: boolean
        received:
          type: string
    GetMessagesKeyTemplateSingleResponse:
      type: object
      properties:
        uniqueId:
          type: string
        from:
          type: array
        to:
          type: array
        cc:
          type: string
        bcc:
          type: string
        subject:
          type: string
        body:
          type: string
        isHtml:
          type: boolean
        received:
          type: string
        templateData:
          type: object
    GetStatusResponse:
      type: object
      properties:
        key:
          type: string
        password:
          type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
security:
- apiKey: []
tags:
- name: Api
- name: Mailboxes
- name: Messages
- name: Status