List messages

email_list_messages · Reads only · Markdown

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

Free*

*Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads.

What came into the support inbox this week?

Your agent callsemail_list_messagesFree*

The example business is Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. The reply is the one the tool really gives.

With these arguments

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

What comes back

{
  "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
}

Use it when

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

For one message in full, use email_get_message.
For a whole conversation, use email_get_thread.

What it does

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

What comes back

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. Every reply also carries cost_usd and balance_usd.

Inputs

Name	Type	What it is
`inbox`	string	Up to 254 characters.
`direction`	string	One of: in,out.
`from`	string	Up to 254 characters.
`state`	string	Only messages whose thread is in this state (email_update_thread). One of: open,waiting,handled,archived.
`label`	string	Only threads with this label. Up to 40 characters.
`since`	string	ISO 8601. Up to 40 characters.
`query`	string	Up to 200 characters.
`limit`	integer	1 to 100. Default: 25.

The call

Over MCP, call email_list_messages on https://api.conecto.chat/mcp/email. Over REST:

Terminal

curl -X POST 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"}'

When it refuses

A refused call costs nothing and says what to do next.

Code	When	What to do
`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.

More Email tools

All 10 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md

List messages

An example

Use it when

What it does

What comes back

Inputs

The call

When it refuses

More Email tools

Give this to your agent.