Audience

The client.audience resource manages everything campaigns send to. Each kind is a sub-resource:

client.audience.contacts;    // individual contacts
client.audience.lists;       // contact lists
client.audience.topics;      // subscription topics
client.audience.properties;  // custom contact properties
client.audience.segments;    // dynamic segments

All list() methods return paginated data with a pagination object (total, per_page, current_page, last_page).

Contacts

import { Lettr } from "lettr";
const client = new Lettr(process.env.LETTR_API_KEY!);

// Create (optionally attach to a list and set properties)
const { data: contact } = await client.audience.contacts.create({
  email: "jane@example.com",
  list_id: "list-uuid",
  properties: { first_name: "Jane", plan: "pro" },
});

// List with filters
const { data, error } = await client.audience.contacts.list({
  page: 1,
  per_page: 50,
  search: "jane",
  status: "subscribed",
  list_id: "list-uuid",
});

if (!error) {
  for (const c of data.contacts) console.log(c.email, c.status);
  console.log(data.pagination.total);
}

// Get, update, delete
await client.audience.contacts.get("contact-uuid");
await client.audience.contacts.update("contact-uuid", {
  status: "unsubscribed",
  properties: { plan: "enterprise" },
});
await client.audience.contacts.delete("contact-uuid");

Contact status is "subscribed", "unsubscribed", "bounced", "complained", or "unverified".

API Reference

GET /audience/contacts

Double opt-in

Pass double_opt_in to create the contact as unverified and send a confirmation email — they become subscribed after clicking the link:

await client.audience.contacts.create({
  email: "jane@example.com",
  double_opt_in: {
    from: "hello@example.com",
    subject: "Confirm your subscription",
    template_slug: "email-confirmation",
    redirect_url: "https://example.com/confirmed",
  },
});

Bulk create contacts

bulkCreate() takes up to 1000 contacts per request in one of two shapes. The flat emails shape gives every address the same lists, properties and topics:

await client.audience.contacts.bulkCreate({
  emails: ["a@example.com", "b@example.com"],
  list_ids: ["list-uuid"],
  properties: { source: "spring-campaign" },
});

The contacts shape addresses each contact individually. Row-level list_ids and topics are applied on top of the batch-wide ones, and a row’s properties key overrides the batch-wide value for that key:

const { data, error } = await client.audience.contacts.bulkCreate({
  contacts: [
    {
      email: "cara@example.com",
      properties: { plan: "pro" },
      list_ids: ["vip-list-uuid"],
      topics: [{ id: "newsletter-uuid", subscription: "opt_in" }],
    },
    {
      email: "dan@example.com",
      topics: [{ id: "promos-uuid", subscription: "opt_out" }],
    },
  ],
  list_ids: ["everyone-list-uuid"],
  properties: { source: "spring-campaign" },
  update_existing: false,
});

Pass emails or contacts, not both — the TypeScript types enforce it.

subscription: "opt_out" suppresses a topic for that contact in the same request. Useful when a topic’s default_subscription is opt_out, which auto-subscribes newly created contacts — a row-level opt_out cancels that instead of needing a second call. A row-level opt_out also beats a batch-level opt_in.

update_existing defaults to false, which leaves existing contacts’ properties alone (they are still attached to the requested lists). Set it to true to merge properties — submitted keys overwrite, absent keys are preserved. It governs properties only: a row-level opt_out drops an existing subscription either way.

Handling the result

error === null does not mean every row landed. Rows that fail validation are skipped and reported in data.errors while the rest of the batch commits — the API still returns 201. Always check data.errors.length.

if (!error) {
  console.log(data.created, data.already_existed, data.updated);

  for (const e of data.errors) {
    // index is zero-based into the rows you submitted
    console.error(`row ${e.index} (${e.email}): ${e.error_code} — ${e.error}`);
  }

  // Every contact that exists after the request, in submission order
  const ids = data.contacts.map((c) => c.id);
}

error_code is one of missing_email, invalid_email, invalid_property_value, unknown_property_key, unknown_list, unknown_topic, or invalid_topic_subscription.

already_existed and updated overlap by design — “was the address already in the audience?” versus “did this request change the contact?” — so they don’t sum to the row count. A contact that already existed and got attached to a list is counted in both.

Bulk membership

data.contacts from a bulkCreate() feeds straight into the bulk membership calls, so no id lookup is needed in between:

// Single list / topic membership
await client.audience.contacts.attachList("contact-uuid", "list-uuid");
await client.audience.contacts.detachList("contact-uuid", "list-uuid");
await client.audience.contacts.subscribeTopic("contact-uuid", "topic-uuid");
await client.audience.contacts.unsubscribeTopic("contact-uuid", "topic-uuid");

// Bulk list membership
await client.audience.contacts.bulkAttachLists({
  contact_ids: ["c1", "c2"],
  list_ids: ["l1", "l2"],
});
await client.audience.contacts.bulkDetachLists({
  contact_ids: ["c1"],
  list_ids: ["l1"],
});

// Bulk topic membership
const { data: sub } = await client.audience.contacts.bulkSubscribeTopics({
  contact_ids: ["c1", "c2"],
  topic_ids: ["t1"],
});
console.log(sub!.subscribed, sub!.already_subscribed, sub!.total_pairs);

const { data: unsub } = await client.audience.contacts.bulkUnsubscribeTopics({
  contact_ids: ["c1"],
  topic_ids: ["t1"],
});
console.log(unsub!.unsubscribed, unsub!.total_pairs);

Both topic calls process every contact_ids × topic_ids combination, up to 1000 contacts × 50 topics. Unsubscribing ignores pairs that don’t exist, so unsubscribed can be lower than total_pairs.

bulkUnsubscribeTopics() and bulkDetachLists() issue a DELETE with a request body. fetch handles that fine, but a proxy in front of your app may not.

API Reference

POST /audience/contacts/bulk

Lists

const { data: list } = await client.audience.lists.create({ name: "Newsletter" });
console.log(list!.id, list!.name, list!.contacts_count);

await client.audience.lists.list({ page: 1, per_page: 20 });
await client.audience.lists.get("list-uuid");
await client.audience.lists.update("list-uuid", { name: "Weekly digest" });
await client.audience.lists.delete("list-uuid");

// Bulk delete
await client.audience.lists.bulkDelete({ list_ids: ["l1", "l2"] });

API Reference

GET /audience/lists

Segments

A segment is a dynamic group defined by conditions. Groups are joined by OR; conditions within a group by AND.

await client.audience.segments.create({
  name: "Pro users at example.com",
  list_id: "list-uuid", // optional: restrict to one list
  conditions: {
    groups: [
      {
        conditions: [
          { field: "email", operator: "ends_with", value: "@example.com" },
          { field: "plan", operator: "equals", value: "pro" },
        ],
      },
    ],
  },
});

await client.audience.segments.list({ list_id: "list-uuid" });
await client.audience.segments.get("segment-uuid");
await client.audience.segments.delete("segment-uuid");

Operators include equals, not_equals, contains, starts_with, ends_with, is_true, is_false, and others.

API Reference

GET /audience/segments

Topics

await client.audience.topics.create({
  name: "Product updates",
  description: "Occasional product news",
  default_subscription: "opt_in",  // "opt_in" | "opt_out" — immutable after creation
  visibility: "public",            // "public" | "private"
});

await client.audience.topics.list({ per_page: 20 });
await client.audience.topics.get("topic-uuid");
await client.audience.topics.update("topic-uuid", { name: "Product news", visibility: "private" });
await client.audience.topics.delete("topic-uuid");

API Reference

GET /audience/topics

Properties

Custom contact properties have an immutable name and type; only the fallback can be updated.

await client.audience.properties.create({
  name: "plan",
  type: "string",         // "string" | "number" | "boolean" | "date" | "json"
  fallback_value: "free",
});

await client.audience.properties.list({ page: 1 });
await client.audience.properties.get("property-uuid");
await client.audience.properties.delete("property-uuid");

API Reference

GET /audience/properties

What’s Next

Campaigns

Send to your audience

API Reference

Full audience API reference

Documentation

Quickstart

Learn

Integrations

Resources

Contacts

API Reference

Double opt-in

Bulk create contacts

Handling the result

Bulk membership

API Reference

Lists

API Reference

Segments

API Reference

Topics

API Reference

Properties

API Reference

What’s Next

Campaigns

API Reference

​Contacts

API Reference

​Double opt-in

​Bulk create contacts

​Handling the result

​Bulk membership

API Reference

​Lists

API Reference

​Segments

API Reference

​Topics

API Reference

​Properties

API Reference

​What’s Next

Campaigns

API Reference

Contacts

Double opt-in

Bulk create contacts

Handling the result

Bulk membership

Lists

Segments

Topics

Properties

What’s Next