List contacts

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

boolean

Filter by subscription state. Omit to return both.

string

Search term matched against email and name.

string

Opaque pagination cursor from a previous response’s nextCursor.

integer

Page size, 1–100 (default 25).

Request

curl "https://api.drin.run/v1/contacts?subscribed=true&limit=50" \
  -H "Authorization: Bearer $DRIN_API_KEY"

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);
}

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.

200 OK

{
  "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"
}

Overview

Emails

Domains

Inboxes

Threads

Inbound

Webhooks

Suppressions

Contacts

Templates

Metrics

API keys

List contacts

Query parameters

Request

Response

​Query parameters

​Request

​Response

Query parameters

Request

Response