List sent messages
well_list_messagesRead-only
List the emails the user sent to other people through Well (with well_send_message), newest first: recipient, subject, body, channel, status and send date. It returns the user's own messages only, never those sent by other members.
Use it when the user asks what was sent, e.g. "what did I send to Acme?" or "did my email to Marie go out?". It reads the same records as well_query_records on the messages root; notifications to the user are not stored, so they never appear. It filters by recipient and category only: to find sent emails about a topic, search them with well_search_context and the "message" entity type instead.
Returns { rows, totalCount, records_url }. Hand records_url to the user when there are more messages than the rows you read.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many messages to return, newest first (default 20). | |
| category | No | Keep only messages of this category. | |
| recipient | No | Keep messages whose recipient email address or recipient name contains this text, e.g. an address, a domain, or a name. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes | Query results | |
| error | No | ||
| end_by | No | The date field path a timeline ends its bars on: the asked one, else the saved view's. Null on any other layout. Each row carries its value. | |
| layout | No | The layout the records card draws and `records_url` opens: the asked one, else the saved view's. Null when neither names one. | |
| totals | No | Present when `sum` was passed and the total read succeeded: the sums over every matching row, one group per currency. `truncated: true` means the group list hit its cap and is incomplete. `completeness` (invoices root only) says how far the workspace's own-side resolution lets you trust the total: the self-party set's size and the counts of the rows it could not prove a side for. | |
| columns | No | The materialized columns in display order, with each composite substituted in place of the source fields it consumed. A row object's key order does not preserve this — the flattener appends reconstructed composites last — so a UI that wants the web app's column order must read it from here. | |
| success | Yes | ||
| group_by | No | The field path a kanban or a calendar groups the rows by, or a timeline starts its bars on: the asked one, else the saved view's. Each row carries its value. | |
| returned | Yes | Number of rows returned | |
| columnMeta | No | Per-column field meaning, keyed by the same column paths as the rows. `context` = what the field means; `enrichment` = how the value is sourced (e.g. Bank sync, AI extraction). Only documented columns appear. Read this to interpret the returned values. | |
| nextCursor | No | Cursor for the next page. null means last page. | |
| totalCount | Yes | Total matching records | |
| party_scope | No | Present only when `partyScope` was passed: what the scope resolved to on this read. `side_unknown: true` means the workspace resolved no own company, so NO side filter was applied (`applied: false`) and the rows and totals cover invoices on BOTH sides — say the side is unknown, never that the figure is the requested side's. | |
| records_url | No | Login-gated deep link to the FULL web-app records table for this root (real DataTable: composites, inline editing, resize/pin), carrying this call's `whereClause` and `orderBy` so it opens on the same rows. Hand it to the user for everything past this page — it is the answer to 'show me all of them', not pagination. Null when no workspace is in context or no web page serves the root. | |
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| workspace_figures | No | Present when a read that names no workspace covered several and passed `sum` or `partyScope`: one entry per workspace it read, with that workspace's own count, totals and side. The top-level `totalCount` adds these counts, including any entry whose side is unknown, and no top-level `totals` exists: an amount belongs to one workspace. A workspace whose read failed has no entry and is named in `error`. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| totals_unavailable | No | Present instead of `totals` when `sum` was passed but no total could be measured (`timeout`, `error`, or `count_mismatch` when the total did not cover the same rows as `totalCount`). The rows are still a page: never add them up to stand in for the total. Say the total is unavailable. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |