import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.messages.list({ limit: 10 });
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.list_messages(limit=10)
print(result)curl 'https://api.mails.ai/v1/messages?limit=10' \
-H "Authorization: Bearer $MAILS_API_KEY"mails emails list --limit 10
mails emails list --agent-id hello --all --json{
"name": "mails_emails_list",
"arguments": { "limit": 10 }
}{
"data": [
{
"id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"from": "jordan@example.com",
"thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"in_reply_to_message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"to": ["jordan@example.com"],
"cc": ["jordan@example.com"],
"bcc": ["jordan@example.com"],
"subject": "<subject>",
"body_text": "<body_text>",
"body_html": "<body_html>",
"classifier_score": 0,
"status": "scheduled",
"refused_recipients": ["jordan@example.com"],
"cost_usd": 0,
"ses_message_id": "<ses_message_id>",
"attachments": [
{
"filename": null,
"content_type": null,
"size_bytes": null,
"content_id": null
}
],
"references": ["<references>"],
"metadata": {},
"tags": [{ "name": null, "value": null }],
"sent_at": "2026-10-04T12:00:00.000Z",
"delivered_at": "2026-10-04T12:00:00.000Z",
"scheduled_at": "2026-10-04T12:00:00.000Z",
"canceled_at": "2026-10-04T12:00:00.000Z",
"bounced_at": "2026-10-04T12:00:00.000Z",
"complained_at": "2026-10-04T12:00:00.000Z",
"forwarded_from": "<forwarded_from>",
"test_mode": false,
"classifier_warning": {
"code": "cold_email_prohibited",
"message": "<message>",
"score": 0,
"reason": "<reason>"
},
"created_at": "2026-10-04T12:00:00.000Z"
}
],
"has_more": false,
"next_cursor": "<next_cursor>"
}200 A page of sent messages.
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
409 Conflict — duplicate resource, an in-progress
idempotent request, a draft or scheduled message
that started sending while it was being changed, or
a thread deleted for good while one of its messages
is being sent (duplicate_resource); or an agent
name more than one agent has (agent_name_conflict:
use the agent's id); or a status change on an
archived agent, since archiving cannot be undone
(agent_archived).
500 Internal server error.List sent messages
import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.messages.list({ limit: 10 });
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.list_messages(limit=10)
print(result)curl 'https://api.mails.ai/v1/messages?limit=10' \
-H "Authorization: Bearer $MAILS_API_KEY"mails emails list --limit 10
mails emails list --agent-id hello --all --json{
"name": "mails_emails_list",
"arguments": { "limit": 10 }
}{
"data": [
{
"id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"from": "jordan@example.com",
"thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"in_reply_to_message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"to": ["jordan@example.com"],
"cc": ["jordan@example.com"],
"bcc": ["jordan@example.com"],
"subject": "<subject>",
"body_text": "<body_text>",
"body_html": "<body_html>",
"classifier_score": 0,
"status": "scheduled",
"refused_recipients": ["jordan@example.com"],
"cost_usd": 0,
"ses_message_id": "<ses_message_id>",
"attachments": [
{
"filename": null,
"content_type": null,
"size_bytes": null,
"content_id": null
}
],
"references": ["<references>"],
"metadata": {},
"tags": [{ "name": null, "value": null }],
"sent_at": "2026-10-04T12:00:00.000Z",
"delivered_at": "2026-10-04T12:00:00.000Z",
"scheduled_at": "2026-10-04T12:00:00.000Z",
"canceled_at": "2026-10-04T12:00:00.000Z",
"bounced_at": "2026-10-04T12:00:00.000Z",
"complained_at": "2026-10-04T12:00:00.000Z",
"forwarded_from": "<forwarded_from>",
"test_mode": false,
"classifier_warning": {
"code": "cold_email_prohibited",
"message": "<message>",
"score": 0,
"reason": "<reason>"
},
"created_at": "2026-10-04T12:00:00.000Z"
}
],
"has_more": false,
"next_cursor": "<next_cursor>"
}200 A page of sent messages.
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
409 Conflict — duplicate resource, an in-progress
idempotent request, a draft or scheduled message
that started sending while it was being changed, or
a thread deleted for good while one of its messages
is being sent (duplicate_resource); or an agent
name more than one agent has (agent_name_conflict:
use the agent's id); or a status change on an
archived agent, since archiving cannot be undone
(agent_archived).
500 Internal server error.Query Parameters
limitinteger
Page size (1–100).
cursorstring
Opaque cursor from a previous page's next_cursor.
agent_idstring
Filter by agent id or name. A key tied to one agent always reads that agent's mail, and naming another agent is a 403.
thread_idstring
Filter by thread id.
qstring
Case-insensitive substring of the subject, body or recipient addresses. For word search across all mail, use GET /v1/search.
Response
dataobject[]
The items on this page, at most limit of them.
has_moreboolean
True when more items follow this page: pass next_cursor as cursor to get them.
next_cursorstring
Pass as cursor to fetch the next page. Absent on the last page.
Was this page helpful?