Interface: ContactsResource

Defined in: packages/sdk/src/resources/contacts.ts:19

The project's first-party contact list: upsert by email, read, filter, opt out.

Example

const contacts = await mailroom.contacts.upsert([
  { email: "ada@example.com", tags: ["beta"] },
  { email: "grace@example.com" },
]);

for await (const contact of mailroom.contacts.listAll({ status: "subscribed" })) {
  console.log(contact.email);
}

Methods

get()

get(id: string, opts?: CallOptions): Promise<Contact>;

Defined in: packages/sdk/src/resources/contacts.ts:36

One contact by id. Throws MailroomNotFoundError when it does not exist.

Parameters

Parameter	Type
id	string
opts?	CallOptions

Returns

Promise<Contact>

---

list()

list(query?: ContactQuery, opts?: CallOptions): Promise<Contact[]>;

Defined in: packages/sdk/src/resources/contacts.ts:27

Single page of contacts (back-compatible: returns just the array).

Parameters

Parameter	Type
query?	ContactQuery
opts?	CallOptions

Returns

Promise<Contact[]>

---

listAll()

listAll(query?: ContactQuery, opts?: CallOptions): AsyncGenerator<Contact, void, void>;

Defined in: packages/sdk/src/resources/contacts.ts:33

Auto-paginating async iterator over every matching contact.

Parameters

Parameter	Type
query?	ContactQuery
opts?	CallOptions

Returns

AsyncGenerator<Contact, void, void>

---

listPage()

listPage(query?: ContactQuery & {
  cursor?: string;
}, opts?: CallOptions): Promise<Page<Contact>>;

Defined in: packages/sdk/src/resources/contacts.ts:30

One cursor page with nextCursor for manual paging.

Parameters

Parameter	Type
query?	ContactQuery & { cursor?: string; }
opts?	CallOptions

Returns

Promise<Page<Contact>>

---

unsubscribe()

unsubscribe(id: string, opts?: CallOptions): Promise<{
  id: string;
  status: "unsubscribed";
}>;

Defined in: packages/sdk/src/resources/contacts.ts:39

Programmatic opt-out — the same effect as the recipient clicking unsubscribe.

Parameters

Parameter	Type
id	string
opts?	CallOptions

Returns

Promise<{ id: string; status: "unsubscribed"; }>

---

upsert()

upsert(input: ContactInput | ContactInput[], opts?: CallOptions): Promise<Contact[]>;

Defined in: packages/sdk/src/resources/contacts.ts:24

Create or update contacts by email — one or an array (max 1000 per call). Idempotent on (project, email): an existing contact keeps its id.

Parameters

Parameter	Type
input	ContactInput | ContactInput[]
opts?	CallOptions

Returns

Promise<Contact[]>