# Find people to DM

> Find people to message from a post's repliers, a search, handles, an X list, recent interactions or a contact list, with whether each can be messaged. Returns the recipients (with preview tokens) that send_dms takes.

`dm.preview_recipients` · write

- **MCP tool:** `dm_preview_recipients`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/dm/preview-recipients`
- **CLI:** `xholic dm preview-recipients`
- **Scope:** `write`
- **Plan:** Pro plan or higher
- **Cost:** Live X lookup: no credits, counts toward the plan's X data limits.
- **Rate limit bucket:** `live_x`

## Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | "FROM_TWEET" \\| "SEARCH" \\| "HANDLES" \\| "X_LIST" \\| "INTERACTIONS" \\| "CONTACT_LIST" | Yes | Where to find people: FROM_TWEET (repliers/reposters of tweetUrl), SEARCH (query), HANDLES (handles), X_LIST (listUrl or numeric listId), INTERACTIONS (people who replied to or reposted the account in the last days), CONTACT_LIST (listId of a contact list). |
| `tweetUrl` | string (uri) ≤ 2048 chars | No |  |
| `includeReplies` | boolean | No |  |
| `includeReposts` | boolean | No |  |
| `keyword` | string ≤ 120 chars or null | No | FROM_TWEET: only replies matching one of these comma-separated terms. |
| `excludeMessagedForPost` | boolean | No |  |
| `continuation` | object or null | No | FROM_TWEET: the continuation from a previous preview, to scan deeper. |
| `query` | string ≤ 80 chars | No |  |
| `handles` | array of string ≤ 120 chars (min 1, max 500) | No |  |
| `listId` | string ≤ 64 chars or null | No | X_LIST: numeric X list id. CONTACT_LIST: the contact list id. |
| `listUrl` | string (uri) ≤ 2048 chars or null | No |  |
| `days` | integer 1–7 | No |  |
| `skipQueued` | boolean | No |  |
| `skipCooldown` | boolean | No |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |