List contacts
Contacts of one list with status, tags and dates, filtered by status, tag, segment or email address.
MCP tool emailoctopus_read → list_contacts
read
Lists the contacts of one list, 50 to a page by default; pass next_cursor back as cursor for the next page. status picks the subscribed, pending or unsubscribed filter of the contacts page. tag and segment filter the way the Tags and Segment drop-downs do, and search matches an email address. The response also returns total, the number of contacts that match the filters. added is when the contact joined the list, last_changed when it was last edited.
Parameters
| Name | Type | Description |
|---|---|---|
| list_id string required | string | List ID from list_lists. |
| status enum | enum | subscribed, pending or unsubscribed. Default: all three. |
| tag string | string | Only contacts with this tag. |
| segment string | string | Name of a segment from list_segments. |
| search string | string | Email address to look for. |
| cursor string | string | next_cursor from the previous call. |
tools/call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "emailoctopus_read",
"arguments": {
"operation": "list_contacts",
"arguments": {
"list_id": "list_8c41d2"
}
}
}
}Example response
{
"content": [
{
"type": "text",
"text": "{ ... same JSON as structuredContent ... }"
}
],
"structuredContent": {
"total": 212,
"contacts": [
{
"contact_id": "e3ab8c80-5f65-11ed-835e-030e4bb63150",
"email_address": "sam@example.com",
"first_name": "Sam",
"last_name": "Reed",
"tags": [
"customer"
],
"status": "subscribed",
"added": "2025-03-04T10:12:00Z",
"last_changed": "2025-03-04T10:12:00Z"
},
{
"contact_id": "f1c2d3e4-6a7b-11ed-9c8d-0242ac120002",
"email_address": "lena@example.org",
"first_name": "Lena",
"last_name": "Novak",
"tags": [],
"status": "subscribed",
"added": "2025-04-18T16:40:00Z",
"last_changed": "2025-06-02T09:05:00Z"
}
],
"next_cursor": "2"
},
"isError": false
}