> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drin.run/llms.txt
> Use this file to discover all available pages before exploring further.

# List contacts

> GET /v1/contacts — list the project's contacts with cursor pagination and optional subscription / search filters.

Return a page of the project's contacts. Filter by subscription state, search by email or name, and page forward with the cursor.

**`GET /v1/contacts`**

## Query parameters

<ParamField query="subscribed" type="boolean">
  Filter by subscription state. Omit to return both.
</ParamField>

<ParamField query="q" type="string">
  Search term matched against email and name.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor from a previous response's `nextCursor`.
</ParamField>

<ParamField query="limit" type="integer">
  Page size, `1`–`100` (default `25`).
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.drin.run/v1/contacts?subscribed=true&limit=50" \
    -H "Authorization: Bearer $DRIN_API_KEY"
  ```

  ```typescript Node.js theme={null}
  import { DrinClient } from "@drin00/sdk";

  const drin = new DrinClient({ apiKey: process.env.DRIN_API_KEY });

  // One page.
  const page = await drin.contacts.list({ subscribed: true, limit: 50 });

  // Or iterate every contact, auto-paging.
  for await (const contact of drin.contacts.paginate({ q: "example.com" })) {
    console.log(contact.email);
  }
  ```
</CodeGroup>

## Response

Returns `200 OK` with a page under `data`. When `nextCursor` is non-null, pass it as `cursor` to fetch the next page. The SDK's `paginate()` iterator does this for you.

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "ct_7Yh2Lp",
      "email": "ada@example.com",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "subscribed": true,
      "unsubscribedAt": null,
      "metadata": { "plan": "pro" },
      "createdAt": "2026-06-02T17:30:00.000Z",
      "updatedAt": "2026-06-02T17:30:00.000Z"
    }
  ],
  "nextCursor": "ct_7Yh2Lp"
}
```