MailgentAPI ReferenceMessages
List Messages
GET /v0/messages
List emails in your agent's inbox. Returns newest first.
Scope: mail:read
GET /v0/messagesQuery 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
{
"messages": [
{
"messageId": "<abc123@gmail.com>",
"threadId": "thd_f8e2a1c4d7b90e3f",
"from": ["customer@gmail.com"],
"to": ["agent-x8k2m@mailgent.dev"],
"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 |
MCP
Tool: mail.list_messages