AgentMail API
REST API for creating inboxes and sending, receiving, searching, and managing threaded email for AI agents. OpenAPI 3.1; Bearer API-key auth.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference
version: 1.0.0
paths:
/v0/agent/sign-up:
post:
operationId: sign-up
summary: Sign Up
description: >-
Create a new agent organization with an inbox and API key. This endpoint is for signing up for the first time.
If you've already signed up, you're all set — just use your existing API key.
A 6-digit OTP is sent to the human's email for verification.
This endpoint is idempotent. Calling it again with the same `human_email` will rotate the API key and resend the
OTP if expired.
The returned API key has limited permissions until the organization is verified via the verify endpoint.
**CLI:**
```bash
agentmail agent sign-up --human-email user@example.com --username my-agent
```
tags:
- agent
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_agent:AgentSignupResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_agent:AgentSignupRequest'
/v0/agent/verify:
post:
operationId: verify
summary: Verify
description: >-
Verify an agent organization using the 6-digit OTP sent to the human's email during sign-up.
On success, the organization is upgraded from `agent_unverified` to `agent_verified`, the send allowlist is
removed, and free plan entitlements are applied.
The OTP expires after 24 hours and allows a maximum of 10 attempts. If you run into any difficulties receiving
the OTP code, you can also create an account on [console.agentmail.to](https://console.agentmail.to) using the
human email address you provided to verify your account.
**CLI:**
```bash
agentmail agent verify --otp-code 123456
```
tags:
- agent
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_agent:AgentVerifyResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_agent:AgentVerifyRequest'
/v0/inboxes:
get:
operationId: list
summary: List Inboxes
description: |-
**CLI:**
```bash
agentmail inboxes list
```
tags:
- inboxes
parameters:
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_:PageToken'
- name: ascending
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Ascending'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_inboxes:ListInboxesResponse'
post:
operationId: create
summary: Create Inbox
description: |-
**CLI:**
```bash
agentmail inboxes create --display-name "My Agent" --username myagent --domain agentmail.to
```
tags:
- inboxes
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_inboxes:Inbox'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
'422':
description: Error response with status 422
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_inboxes:CreateInboxRequest'
/v0/inboxes/{inbox_id}:
get:
operationId: get
summary: Get Inbox
description: |-
**CLI:**
```bash
agentmail inboxes get --inbox-id <inbox_id>
```
tags:
- inboxes
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_inboxes:Inbox'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
patch:
operationId: update
summary: Update Inbox
description: |-
**CLI:**
```bash
agentmail inboxes update --inbox-id <inbox_id> --display-name "Updated Name"
```
tags:
- inboxes
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_inboxes:Inbox'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
requestBody:
description: Expects an object; provide at least one of `display_name` or `metadata`.
content:
application/json:
schema:
$ref: '#/components/schemas/type_inboxes:UpdateInboxRequest'
delete:
operationId: delete
summary: Delete Inbox
description: |-
**CLI:**
```bash
agentmail inboxes delete --inbox-id <inbox_id>
```
tags:
- inboxes
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful response
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
/v0/inboxes/{inbox_id}/threads:
get:
operationId: list
summary: List Threads
description: |-
Lists threads in the inbox, most recent first. Pass `senders`,
`recipients`, or `subject` to filter by substring. Filtered requests are
served by search, which caps `limit` at 100. For relevance-ranked
full-text search, use `Search Threads`.
**CLI:**
```bash
agentmail inboxes:threads list --inbox-id <inbox_id>
```
tags:
- inboxes > threads
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_:PageToken'
- name: labels
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Labels'
- name: before
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Before'
- name: after
in: query
required: false
schema:
$ref: '#/components/schemas/type_:After'
- name: ascending
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Ascending'
- name: include_spam
in: query
required: false
schema:
$ref: '#/components/schemas/type_:IncludeSpam'
- name: include_blocked
in: query
required: false
schema:
$ref: '#/components/schemas/type_:IncludeBlocked'
- name: include_unauthenticated
in: query
required: false
schema:
$ref: '#/components/schemas/type_:IncludeUnauthenticated'
- name: include_trash
in: query
required: false
schema:
$ref: '#/components/schemas/type_:IncludeTrash'
- name: senders
in: query
description: Filter to threads whose senders contain this value (substring match). Repeatable; all values must match.
required: false
schema:
type: array
items:
type: string
- name: recipients
in: query
description: Filter to threads whose recipients contain this value (substring match). Repeatable; all values must match.
required: false
schema:
type: array
items:
type: string
- name: subject
in: query
description: Filter to threads whose subject contains this value (substring match). Repeatable; all values must match.
required: false
schema:
type: array
items:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_threads:ListThreadsResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
/v0/inboxes/{inbox_id}/threads/search:
get:
operationId: search
summary: Search Threads
description: |-
Full-text search across threads in the inbox, ranked by relevance. The
query is matched against senders, recipients, and subject (substring)
and the message body (tokenized full text). Spam, trash, blocked, and
unauthenticated threads are always excluded. `limit` cannot exceed 100.
tags:
- inboxes > threads
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: q
in: query
required: true
schema:
$ref: '#/components/schemas/type_:Query'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_:PageToken'
- name: before
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Before'
- name: after
in: query
required: false
schema:
$ref: '#/components/schemas/type_:After'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_threads:SearchThreadsResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
/v0/inboxes/{inbox_id}/threads/{thread_id}:
get:
operationId: get
summary: Get Thread
description: |-
**CLI:**
```bash
agentmail inboxes:threads get --inbox-id <inbox_id> --thread-id <thread_id>
```
tags:
- inboxes > threads
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: thread_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_threads:ThreadId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_threads:Thread'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
patch:
operationId: update
summary: Update Thread
description: >-
Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with
a `422` for threads with 100 or more messages.
tags:
- inboxes > threads
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: thread_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_threads:ThreadId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_threads:UpdateThreadResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
'422':
description: Error response with status 422
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_threads:UpdateThreadRequest'
delete:
operationId: delete
summary: Delete Thread
description: |-
Permanently deletes a thread and all of its messages.
**CLI:**
```bash
agentmail inboxes:threads delete --inbox-id <inbox_id> --thread-id <thread_id>
```
tags:
- inboxes > threads
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: thread_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_threads:ThreadId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful response
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
/v0/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}:
get:
operationId: get-attachment
summary: Get Attachment
description: >-
**CLI:**
```bash
agentmail inboxes:threads get-attachment --inbox-id <inbox_id> --thread-id <thread_id> --attachment-id
<attachment_id>
```
tags:
- inboxes > threads
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: thread_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_threads:ThreadId'
- name: attachment_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_attachments:AttachmentId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_attachments:AttachmentResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
/v0/inboxes/{inbox_id}/messages:
get:
operationId: list
summary: List Messages
description: |-
Lists messages in the inbox, most recent first. Pass `from`, `to`, or
`subject` to filter by substring. Filtered requests are served by
search, which caps `limit` at 100. For relevance-ranked full-text
search across sender, recipients, subject, and message body, use
`Search Messages`.
**CLI:**
```bash
agentmail inboxes:messages list --inbox-id <inbox_id>
```
tags:
- inboxes > messages
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_:PageToken'
- name: labels
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Labels'
- name: before
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Before'
- name: after
in: query
required: false
schema:
$ref: '#/components/schemas/type_:After'
- name: ascending
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Ascending'
- name: include_spam
in: query
required: false
schema:
$ref: '#/components/schemas/type_:IncludeSpam'
- name: include_blocked
in: query
required: false
schema:
$ref: '#/components/schemas/type_:IncludeBlocked'
- name: include_unauthenticated
in: query
required: false
schema:
$ref: '#/components/schemas/type_:IncludeUnauthenticated'
- name: include_trash
in: query
required: false
schema:
$ref: '#/components/schemas/type_:IncludeTrash'
- name: from
in: query
description: Filter to messages whose sender contains this value (substring match). Repeatable; all values must match.
required: false
schema:
type: array
items:
type: string
- name: to
in: query
description: >-
Filter to messages whose recipients (to, cc, or bcc) contain this value (substring match). Repeatable; all
values must match.
required: false
schema:
type: array
items:
type: string
- name: subject
in: query
description: Filter to messages whose subject contains this value (substring match). Repeatable; all values must match.
required: false
schema:
type: array
items:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:ListMessagesResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
/v0/inboxes/{inbox_id}/messages/search:
get:
operationId: search
summary: Search Messages
description: |-
Full-text search across messages in the inbox, ranked by relevance. The
query is matched against the sender, recipients, and subject (substring)
and the message body (tokenized full text). Spam, trash, blocked, and
unauthenticated messages are always excluded. `limit` cannot exceed 100.
tags:
- inboxes > messages
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: q
in: query
required: true
schema:
$ref: '#/components/schemas/type_:Query'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_:PageToken'
- name: before
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Before'
- name: after
in: query
required: false
schema:
$ref: '#/components/schemas/type_:After'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:SearchMessagesResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
/v0/inboxes/{inbox_id}/messages/{message_id}:
get:
operationId: get
summary: Get Message
description: |-
**CLI:**
```bash
agentmail inboxes:messages get --inbox-id <inbox_id> --message-id <message_id>
```
tags:
- inboxes > messages
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: message_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_messages:MessageId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:Message'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
patch:
operationId: update
summary: Update Message
description: >-
**CLI:**
```bash
agentmail inboxes:messages update --inbox-id <inbox_id> --message-id <message_id> --add-label read
--remove-label unread
```
tags:
- inboxes > messages
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: message_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_messages:MessageId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:UpdateMessageResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:UpdateMessageRequest'
delete:
operationId: delete
summary: Delete Message
description: |-
Permanently deletes a message.
**CLI:**
```bash
agentmail inboxes:messages delete --inbox-id <inbox_id> --message-id <message_id>
```
tags:
- inboxes > messages
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: message_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_messages:MessageId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful response
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
/v0/inboxes/{inbox_id}/messages/batch-get:
post:
operationId: batch-get
summary: Batch Get Messages
description: |-
Fetch metadata for up to 500 messages in one request. Missing or
restricted IDs are silently omitted; compare `count` against `limit`
to detect misses.
**CLI:**
```bash
agentmail inboxes:messages batch-get --inbox-id <inbox_id> --message-id <id1> --message-id <id2>
```
tags:
- inboxes > messages
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:BatchGetMessagesResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:BatchGetMessagesRequest'
/v0/inboxes/{inbox_id}/messages/batch-update:
post:
operationId: batch-update
summary: Batch Update Messages
description: >-
Apply one label change to up to 50 messages in a single request. The
same add_labels and remove_labels apply to every message id, and at
least one of them must be provided. The update is atomic: either all
resolved messages are updated or none are. Missing or restricted ids
are silently excluded; compare `count` against `limit` to detect
exclusions.
**CLI:**
```bash
agentmail inboxes:messages batch-update --inbox-id <inbox_id> --message-id <id1> --message-id <id2> --add-label
read --remove-label unread
```
tags:
- inboxes > messages
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:BatchUpdateMessagesResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/co
# --- truncated at 32 KB (271 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/agentmail/refs/heads/main/openapi/agentmail-openapi-original.yml