openmail-sh Threads API
Conversation threads and read status
Conversation threads and read status
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/openmail-sh:openmail-sh-threads-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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