mailerpress/list-contacts returns a paginated list of MailerPress contacts, with free-text search over email and name.
It is the directory read; the detail is per contact.
At a glance
| Ability | mailerpress/list-contacts |
| Toolset | MailerPress — toolset/mailerpress |
| Group | MailerPress › Contacts |
| Requires | AcrossAI Pro, plus MailerPress active on the site |
| Capability | manage_options |
| Safety | Read-only — changes nothing |
| Repeatable | Idempotent — running it twice leaves the same result |
| Ships in | AcrossAI Pro 0.9.16 and later |
How it works
Search covers email and name together, which is usually what somebody has — a support request arrives with one or the other and rarely with an ID.
For an exact email match, mailerpress/get-contact-by-email is more direct and returns the full record including lists, tags, custom fields and status.
The status on each row is the one field worth reading carefully. A contact can be subscribed, pending confirmation, unsubscribed or bounced, and only the first receives campaigns.
Pending is the state that accumulates on double-opt-in sites: somebody signed up, never clicked the confirmation, and sits in the list forever without ever receiving anything.
Counting those is a list-health question that nothing surfaces directly, and mailerpress/get-dashboard-contacts is the closest thing to a trend.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
search | string | No | Free text over email and name. |
per_page | integer | No | Rows per page. |
page | integer | No | Page number. |
What comes back
| Name | Type | What it is |
|---|---|---|
contacts | array | Each contact with email, name and status. |
total | integer | How many matched. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Find that contact.
It resolves to one call:
{
"ability": "mailerpress/list-contacts",
"parameters": {
"search": "sam@example.com"
}
}Worth knowing
- Only subscribed contacts receive campaigns.
- Pending contacts accumulate on double-opt-in sites and never receive anything.
- An exact email lookup is a more direct call.
- Read-only.
Related abilities
- MailerPress Get Contact By Email — the full record
- MailerPress Check Email Validity — before creating one
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category