Contacts

A lightweight address book scoped to each project — store the people you email, attach your own metadata, and track their subscribe state. It’s a record-keeping layer, not a marketing list. Contacts let you keep names, custom metadata, and subscribe status alongside an email address. Each project has its own address book. Drin stays transactional — there are no broadcasts or campaigns here — but a contact record is a convenient home for the data your own send logic reads.

Contacts vs suppressions. A contact’s subscribed flag is your opt-in state — you decide what it means and whether to honour it before sending. Suppressions are enforced by Drin at send time and populated automatically by bounces and complaints. They’re separate systems; unsubscribing a contact does not suppress the address, and vice versa.

Create a contact

POST /v1/contacts Only email is required. firstName, lastName, subscribed (defaults to true), and an arbitrary metadata object are optional.

curl https://api.drin.run/v1/contacts \
  -H "Authorization: Bearer $DRIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "firstName": "Sam",
    "lastName": "Rivera",
    "metadata": { "plan": "pro" }
  }'

const contact = await drin.contacts.create({
  email: "sam@example.com",
  firstName: "Sam",
  lastName: "Rivera",
  metadata: { plan: "pro" },
});

201 Contact

{
  "id": "ct_0K3a…",
  "email": "sam@example.com",
  "firstName": "Sam",
  "lastName": "Rivera",
  "subscribed": true,
  "unsubscribedAt": null,
  "metadata": { "plan": "pro" },
  "createdAt": "2026-06-02T09:00:00Z",
  "updatedAt": "2026-06-02T09:00:00Z"
}

List & search

GET /v1/contacts Cursor-paged like every list endpoint. Filter with subscribed=true|false and search names and email with q.

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

# Only subscribed, matching a search term
curl "https://api.drin.run/v1/contacts?subscribed=true&q=rivera" \
  -H "Authorization: Bearer $DRIN_API_KEY"

// Auto-page every subscribed contact.
for await (const c of drin.contacts.paginate({ subscribed: true })) {
  console.log(c.email, c.firstName);
}

Update

PATCH /v1/contacts/{id} Partial update — send only the fields you want to change. firstName and lastName accept null to clear them. To change subscribe state, use the dedicated endpoints below rather than patching it directly.

curl -X PATCH https://api.drin.run/v1/contacts/ct_0K3a \
  -H "Authorization: Bearer $DRIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lastName": null, "metadata": { "plan": "scale" } }'

await drin.contacts.update("ct_0K3a", {
  lastName: null,                 // clear a field by sending null
  metadata: { plan: "scale" },
});

Unsubscribe & resubscribe

POST /v1/contacts/{id}/unsubscribe Unsubscribing flips subscribed to false and stamps unsubscribedAt. Resubscribing flips it back and clears the timestamp. Both return the updated contact.

# Unsubscribe (stamps unsubscribedAt, flips subscribed → false)
curl -X POST https://api.drin.run/v1/contacts/ct_0K3a/unsubscribe \
  -H "Authorization: Bearer $DRIN_API_KEY"

# Resubscribe (clears unsubscribedAt, flips subscribed → true)
curl -X POST https://api.drin.run/v1/contacts/ct_0K3a/resubscribe \
  -H "Authorization: Bearer $DRIN_API_KEY"

await drin.contacts.unsubscribe("ct_0K3a");
// …later…
await drin.contacts.resubscribe("ct_0K3a");

Honouring opt-out. These endpoints record intent — they don’t block sending on their own. Check subscribed in your own send path, or add the address to suppressions when you want Drin to enforce the opt-out at the gateway.

Delete

DELETE /v1/contacts/{id} Permanently removes the contact record. Returns 204 No Content. This deletes the address-book entry only — it has no effect on already-sent messages or the suppression list.

cURL

curl -X DELETE https://api.drin.run/v1/contacts/ct_0K3a \
  -H "Authorization: Bearer $DRIN_API_KEY"

Suppressions

The enforced do-not-send list — separate from contact opt-out.

Send email

Read a contact, decide on subscribed, then send.

Contacts API

Every parameter and response schema for the contacts endpoints.

TypeScript SDK

The drin.contacts resource and .paginate().

Get started

Sending

Receiving

Domains & deliverability

Agents & SDKs

Account

Create a contact

List & search

Update

Unsubscribe & resubscribe

Delete

Suppressions

Send email

Contacts API

TypeScript SDK

​Create a contact

​List & search

​Update

​Unsubscribe & resubscribe

​Delete

​Related

Suppressions

Send email

Contacts API

TypeScript SDK

Create a contact

List & search

Update

Unsubscribe & resubscribe

Delete

Related