List contacts
list_contactsRead-onlyIdempotent
Search and list contacts from MailFathom's address book by name or address, filter by origin, and paginate with a cursor. Reads local data only.
Instructions
Lists people from MailFathom's own contact book, ordered by name, with the addresses each of them uses. Reads local state only: it never contacts a mail server and changes nothing. Narrow the page with search, which matches text anywhere in a name or an address without regard to case, and with origin. Returns at most 200 contacts per call and 50 by default, with an opaque cursor for the next page; there is no way to ask for the whole book in one call. To resolve one address to the person using it, call get_contact with that address rather than searching for it here.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | The nextCursor value from a previous call, to read the following page. It stays valid when search or origin changes, because the book is walked in one order whatever narrows it. | |
| origin | No | Return only contacts of this origin: asserted for the people somebody wrote down, collected for the addresses this deployment picked up from mail that arrived. Omit to list both. | |
| search | No | Return only contacts carrying this text in their name or in one of their addresses. Matched anywhere in the value and without regard to case, up to 320 characters. Wildcard characters match themselves. Omit to list the whole book, which an empty string does too. | |
| pageSize | No | How many contacts to return, from 1 to 200. Omit to take the default of 50. A value outside the range is refused rather than clamped. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| contacts | Yes | The contacts on this page, ordered by name and then by identifier. Empty when nobody matched. | |
| nextCursor | No | An opaque cursor for the next page. Pass it back unchanged as cursor. Null means this page ended the walk. It stays valid when the search or the origin filter changes, because the book is walked in one order whatever narrows it, and no filter makes continuing from it skip or repeat a contact. A rename does: the cursor is a position in the order rather than a snapshot of it, so somebody renamed between two pages may be served twice or not at all. |