openmail-sh Threads API

openapi: 3.2.0
info:
  title: OpenMail Threads API
  description: Email infrastructure API for AI agents. Create inboxes, send and receive email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
- url: https://api.openmail.sh
security:
- bearerAuth: []
tags:
- name: Threads
  description: Conversation threads and read status
paths:
  /v1/inboxes/{id}/threads:
    get:
      operationId: listThreads
      summary: List threads
      tags:
      - Threads
      description: List threads for an inbox. Use isRead to filter by read status — for example, ?isRead=false returns only unread threads. (snake_case is_read is accepted as an alias.)
      parameters:
      - schema:
          type: integer
          default: 50
        in: query
        name: limit
        required: false
      - schema:
          type: integer
          default: 0
        in: query
        name: offset
        required: false
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
        in: query
        name: isRead
        required: false
        description: Filter by read status. true = read threads only, false = unread threads only. Omit to return all.
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
        in: query
        name: is_read
        required: false
        description: Alias of isRead, kept for compatibility. Prefer isRead.
      - schema:
          type: string
        in: path
        name: id
        required: true
      responses:
        '200':
          description: List of threads
          content:
            application/json:
              schema:
                description: List of threads
                type: object
                additionalProperties: true
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Thread'
                  total:
                    type: integer
        '401':
          description: Missing, invalid, or expired API key
          content:
            application/json:
              schema:
                description: Missing, invalid, or expired API key
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                description: Inbox not found
                allOf:
                - $ref: '#/components/schemas/Error'
  /v1/threads/{id}/messages:
    get:
      operationId: getThreadMessages
      summary: Get thread messages
      tags:
      - Threads
      description: Retrieve a thread and all of its messages in order, with read status and full message content.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      responses:
        '200':
          description: Thread with messages
          content:
            application/json:
              schema:
                description: Thread with messages
                type: object
                additionalProperties: true
                properties:
                  threadId:
                    type: string
                  inboxId:
                    type: string
                    description: Inbox this thread belongs to
                  subject:
                    type: string
                  isRead:
                    type: boolean
                    description: Whether the thread has been marked as read
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          description: Missing, invalid, or expired API key
          content:
            application/json:
              schema:
                description: Missing, invalid, or expired API key
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Thread not found
          content:
            application/json:
              schema:
                description: Thread not found
                allOf:
                - $ref: '#/components/schemas/Error'
  /v1/threads/{id}:
    delete:
      operationId: deleteThread
      summary: Delete thread
      tags:
      - Threads
      description: Move a thread and all of its messages to Trash. The API stops returning it. In the console it sits under Trash, where it can be restored or deleted for good; unrestored threads are deleted automatically after 30 days.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      responses:
        '204':
          description: Thread deleted
        '401':
          description: Missing, invalid, or expired API key
          content:
            application/json:
              schema:
                description: Missing, invalid, or expired API key
                allOf:
                - $ref: '#/components/schemas/Error'
        '403':
          description: API key is inbox-scoped, or is not scoped to this thread's inbox. Deleting mail needs an account-wide or pod-scoped key.
          content:
            application/json:
              schema:
                description: API key is inbox-scoped, or is not scoped to this thread's inbox. Deleting mail needs an account-wide or pod-scoped key.
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Thread not found
          content:
            application/json:
              schema:
                description: Thread not found
                allOf:
                - $ref: '#/components/schemas/Error'
    patch:
      operationId: updateThread
      summary: Update thread
      tags:
      - Threads
      description: Update a thread's read status. Use this to mark a thread as read after your agent has processed it, or as unread to re-queue it for later processing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              anyOf:
              - required:
                - isRead
              - required:
                - is_read
              properties:
                isRead:
                  type: boolean
                  description: Set to true to mark as read, false to mark as unread
                is_read:
                  type: boolean
                  description: Alias of isRead, kept for compatibility. Prefer isRead.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      responses:
        '200':
          description: Thread updated
          content:
            application/json:
              schema:
                description: Thread updated
                type: object
                additionalProperties: true
                properties:
                  ok:
                    type: boolean
        '404':
          description: Thread not found
          content:
            application/json:
              schema:
                description: Thread not found
                allOf:
                - $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
    Thread:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
        subject:
          type: string
        isRead:
          type: boolean
          description: Whether the thread has been marked as read. Defaults to false for new inbound threads. Auto-set to true when a reply is sent.
        lastMessageAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        messageCount:
          type: integer
    Message:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
        threadId:
          type: string
        direction:
          $ref: '#/components/schemas/MessageDirection'
        fromAddr:
          type: string
        toAddr:
          type: string
          description: Your OpenMail inbox address for inbound messages. For outbound sends, the primary recipient.
        headerTo:
          type:
          - string
          - 'null'
          description: Inbound only. The address the sender wrote to (comma-separated if multiple). When deliveryRole is cc, reply to this address — not fromAddr.
        deliveryRole:
          type:
          - string
          - 'null'
          enum:
          - to
          - cc
          - null
          description: Inbound only. to if your inbox was the main recipient; cc if you were copied on the email.
        cc:
          type: array
          items:
            type: string
          description: Email addresses copied on the message.
        addressNames:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: 'Inbound only. Display names the sender''s mail client put on From, To and Cc, keyed by lower-cased address, e.g. `{"alice@example.com": "Alice Smith"}`. Address fields stay bare so you can match on them. Null when the headers carried no names.'
        bcc:
          type: array
          items:
            type: string
          description: Blind-copy recipients on outbound mail sent from this inbox. Empty on inbound. Not included in the copy delivered to To or Cc.
        subject:
          type: string
        bodyText:
          type: string
        bodyHtml:
          type: string
        attachments:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              filename:
                type: string
              contentType:
                type: string
              sizeBytes:
                type: integer
              url:
                type: string
                description: Signed URL for download
        rawUrl:
          type:
          - string
          - 'null'
          description: URL of the original RFC 822 message (GET /v1/messages/{id}/raw). null when the bytes weren't kept.
        status:
          type: string
          enum:
          - pending
          - sent
          - received
          - failed
        createdAt:
          type: string
          format: date-time
    MessageDirection:
      type: string
      enum:
      - inbound
      - outbound
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key