---
name: "email_list_messages"
area: "email"
title: "List messages"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/email_list_messages"
mcp_server: "https://api.conecto.chat/mcp/email"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/email/email_list_messages"
---

# List messages (`email_list_messages`)

Messages in the business's inboxes, newest first: received, sent or both, for one inbox, one sender or since a time.

Messages in this account's inboxes, newest first: received, sent or both, optionally for one inbox, one sender or since a time. Free.

Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing.

## Use it when

To see what arrived, or to find a message to answer.

- For one message in full, use [email_get_message](https://conecto.chat/tools/email/email_get_message.md).
- For a whole conversation, use [email_get_thread](https://conecto.chat/tools/email/email_get_thread.md).

## Say this to your agent

> What came into the support inbox this week?

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `inbox` | string | no | Up to 254 characters. |  |  |
| `direction` | string | no |  | `"in"`, `"out"` |  |
| `from` | string | no | Up to 254 characters. |  |  |
| `state` | string | no | Only messages whose thread is in this state (email_update_thread). | `"open"`, `"waiting"`, `"handled"`, `"archived"` |  |
| `label` | string | no | Only threads with this label. Up to 40 characters. |  |  |
| `since` | string | no | ISO 8601 (up to 40 characters) |  |  |
| `query` | string | no | Up to 200 characters. |  |  |
| `limit` | integer | no | 1 to 100. |  | `25` |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `email_list_messages` on the MCP server `https://api.conecto.chat/mcp/email` with these arguments:

```json
{
  "inbox": "support@halverson-cycle-repair.useconecto.com",
  "direction": "in",
  "since": "2026-10-12T00:00:00-07:00"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/email_list_messages \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbox": "support@halverson-cycle-repair.useconecto.com", "direction": "in", "since": "2026-10-12T00:00:00-07:00"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "email_list_messages",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "messages": [
      {
        "message_id": "e9ce0416-a7a2-48d4-a828-408662774d9b",
        "inbox": "support@halverson-cycle-repair.useconecto.com",
        "direction": "in",
        "from": "paul.hoffmann@example.com",
        "from_name": "Paul Hoffmann",
        "to": [
          "support@halverson-cycle-repair.useconecto.com"
        ],
        "cc": [],
        "subject": "My Tabor's repair",
        "at": "2026-10-14T08:00:00+00:00",
        "thread": "<CAF7d2k1x@mail.example.com>",
        "thread_state": "open",
        "thread_labels": [],
        "contact_id": 4101,
        "spam": "PASS",
        "ticket": 1,
        "preview": "Hello, my Tabor was due back from its repair yesterday. Can you tell me when I can pick it up?\n\nPaul\n"
      }
    ],
    "count": 1
  }
}
```

`result`: Up to 100 messages, newest first, each with its message_id, inbox, direction, from, to, subject, time, thread, contact_id, ticket and the first 200 characters, and how many were listed.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `not_found` | 404 | No active inbox of the business has that address. | Call email_list_inboxes and use one of its addresses. |
| `invalid_input` | 400 | since is not an ISO 8601 time. | Send it like 2026-10-12T00:00:00-07:00. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [email_create_inbox](https://conecto.chat/tools/email/email_create_inbox.md): A new email address for the business on its own subdomain, which sends and receives at once. $1.00 a call.
- [email_list_inboxes](https://conecto.chat/tools/email/email_list_inboxes.md): The business's inboxes, whether each opens tickets or saves attachments, and when each renews. Free up to 1,000,000 reads a month.
- [email_update_inbox](https://conecto.chat/tools/email/email_update_inbox.md): Changes an inbox's sender name, switches saving its attachments to the file store on or off, or changes how much it saves a day. $0.001 a call.
- [email_send](https://conecto.chat/tools/email/email_send.md): Sends an email from one of the business's inboxes, with files from the store attached, or answers a received message in its thread. $0.001 per recipient, plus $0.001 per started MB of attachments for each recipient ($0.001 to one person without attachments), up to $0.52.
- [email_get_message](https://conecto.chat/tools/email/email_get_message.md): One message in full: its text, HTML and attachment names. Free up to 1,000,000 reads a month.
- [email_get_thread](https://conecto.chat/tools/email/email_get_thread.md): Every message of one conversation, oldest first. Free up to 1,000,000 reads a month.
- [email_update_thread](https://conecto.chat/tools/email/email_update_thread.md): Marks an email thread open, waiting, handled or archived, and sets its labels. $0.001 a call.
- [email_save_attachments](https://conecto.chat/tools/email/email_save_attachments.md): Saves the files attached to one received email into the file store, each linked to the email. $0.001 per file saved.
- [email_release_inbox](https://conecto.chat/tools/email/email_release_inbox.md): Stops renting an inbox: mail sent to it later bounces, and its stored messages stay readable. Free.