SDK / API ReferenceMessages
List Messages
GET /v0/messages
Scope: mail:read
List emails in your agent's inbox. Returns newest first.
Request
import { Loomal } from "@loomal/sdk";
const loomal = new Loomal({ apiKey: process.env.LOOMAL_API_KEY! });
const { messages, nextPageToken } = await loomal.mail.listMessages({
limit: 10,
labels: "unread",
});import os
from loomal import Loomal
loomal = Loomal(api_key=os.environ["LOOMAL_API_KEY"])
result = loomal.mail.list_messages(limit=10, labels="unread")loomal mail list --limit 10 --labels unreadUse --page-token to paginate. Omit flags to fetch the default 50 newest messages.
mail.list_messages(limit?, labels?, page_token?)Available through @loomal/mcp — see MCP setup.
curl "https://api.loomal.ai/v0/messages?limit=10&labels=unread" \
-H "Authorization: Bearer loid-your-api-key"Query Parameters
| Param | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | Max results (max 100) |
labels | string | — | Comma-separated label filter |
pageToken | string | — | Cursor from previous response |
Response — 200 OK
{
"messages": [
{
"messageId": "<abc123@gmail.com>",
"threadId": "thd_f8e2a1c4d7b90e3f",
"inboxId": "agent-x8k2m@mailgent.dev",
"from": ["customer@gmail.com"],
"to": ["agent-x8k2m@mailgent.dev"],
"cc": [],
"subject": "Question about pricing",
"text": "Hi, I'd like to know about your plans.",
"extractedText": "Hi, I'd like to know about your plans.",
"labels": ["received", "unread"],
"createdAt": "2026-03-28T12:00:00.000Z"
}
],
"count": 1,
"nextPageToken": "2026-03-28T11:00:00.000Z"
}Filter Examples
# Unread messages only
GET /v0/messages?labels=unread
# Sent messages only
GET /v0/messages?labels=sent
# Multiple labels (AND)
GET /v0/messages?labels=received,high-priority
# With pagination
GET /v0/messages?limit=10&pageToken=2026-03-28T09:00:00.000ZFields
| Field | Description |
|---|---|
text | Full plain text body |
extractedText | Reply-only text (quoted history stripped) — ideal for LLMs |