Skip to main content

​
Static contact lists

A contact list is a saved, hand-curated set of contacts. You decide exactly who is on it, and membership changes only when you (or an API call) add or remove someone. Use lists for one-off blasts, re-engagement waves, VIP cohorts, and any audience where a human picked the members. Everything below works in the dashboard under Audience → Lists and over the Contacts API under /api/v1/contacts/lists.

​
1. Lists vs segments

Both target groups of contacts, but they answer different questions. Pick a list when the audience is a decision, not a query: the 400 contacts legal approved for a regulatory notice, the lapsed customers you want to win back with one dedicated wave, the VIPs a success manager hand-picked. Pick a segment when the audience is a standing rule that should keep itself current — see Build CDP segments and the segment recompute model for how membership stays materialized.

​
2. Create, edit, duplicate, delete

Create a list with a name and an optional description — up to 100 characters for the name and 500 for the description:
In the dashboard, Create list opens the same two fields. Once a list exists, each card on the Lists page carries three actions:
  • Edit renames the list or rewrites its description. Membership is untouched.
  • Duplicate clones the list and copies every member into it. The new list is named after the source with a copy suffix, so an approved roster can branch into a second wave without re-curating. Over the API, POST /api/v1/contacts/lists/{id}/duplicate returns the new list plus the count of members copied.
  • Delete removes the list and its member associations. The confirmation states how many contacts will be detached before you commit. Deleting a list never deletes the contacts themselves — they stay in your workspace, only the grouping is gone.

​
3. Members

Open a list to see its members panel: a searchable table of the members with name, phone, and email per row, and the list’s member count in the header. Add members in three ways:
  • Search and pick. The add-members box searches your contacts as you type and shows matching rows. Click matches to stage them — each pick becomes a removable chip — then commit the whole selection in one request. The bulk endpoint POST /api/v1/contacts/lists/{id}/members/bulk accepts up to 1,000 contact ids per call, so curating a large roster is a handful of commits, not one request per person.
  • Direct identifier. Paste a phone number (E.164 or national format — it is normalized server-side), an email, or a contact id and press Add: POST /api/v1/contacts/lists/{id}/members with { "identifier": "+15550101234" }, or { "contact_id": "cnt_…" } when you already know the canonical id. A known id added twice is a no-op — the response reports the contact was already a member rather than duplicating the row.
  • Import. If the roster lives in a CSV, import it as contacts and attach them to a list in one pass — see Import contacts.
Remove a member from the row’s Remove action (confirming first — the dialog reassures the contact can be re-added later). Over the API, DELETE /api/v1/contacts/lists/{id}/members/{memberId} removes one member. Removal detaches the contact from this list only; the contact itself, and its place in every other list and segment, is untouched. Lists do not go stale on their own — no one joins or leaves unless someone acts. That is the point, and it is also the discipline: a list built for a regulatory notice should be re-curated before its second use, because nothing in the platform will remove a contact who has since unsubscribed from a category. Eligibility (consent, opt-outs, quiet hours) is still enforced at send time by the messaging pipeline, but membership itself is frozen until you touch it.

​
4. Starter templates

On an empty workspace the Lists page offers four one-click starter lists. Each template creates an empty list with a pre-filled name and description you can edit after creation; members are then added the usual way. Templates are starting points, not rules: a templated list behaves exactly like one you created by hand.

​
5. Export

Two CSV exports answer two different questions:
  • Export the lists themselves from the Lists page header. The file carries one row per list — list id, name, description, member count, and created/updated timestamps (rendered in your timezone) — which is the catalogue answer to “what audiences do we have curated right now?”. An active search is honoured: export downloads the set you are looking at. Exports stop at 50,000 lists; narrow the search if you need a fully unfiltered download past that.
  • Export a list’s members from the members panel of an open list. The file carries one row per member — name, phone, email — which is the recipient-roster answer for a send you want to review or reconcile offline. The active member filter is honoured the same way, and the same 50,000-row cap applies.
For compliance workflows: a member export is a snapshot of membership, not a data-subject extract. When a person is erased through a data-subject request, their contact record and every list association go with it — lists recompute their member counts automatically. See Data subject requests for erasure mechanics, and Ad-hoc audience CSV export when you need a one-off export built from a filter you have not saved as either a list or a segment.

​
6. Target a list from a campaign

A saved list is directly targetable by campaigns, broadcasts, and flows. Over the campaigns API, target it with audience_type: "list" and the list id:
The preview returns the resolved member count plus a sample, so you can confirm the roster before launch. At send time the difference from segment targeting is when membership is frozen:
  • A list resolves to the members it holds when the audience resolves — a fixed roster. Contacts added to the list after the send resolves are not swept into an in-flight send.
  • A segment can re-evaluate its filter at send time, so a growing segment keeps working without anyone updating the campaign.
Choose per the table in section 1; either way, confirm the resolved count with the audience preview before launch. The full campaign field reference is in Campaign end-to-end.

​
7. Route change

Lists used to live under Contacts → Lists as a tab on the Contacts hub. They now live under Audience → Lists, alongside segments. Old /contacts/lists links and bookmarks keep working — they redirect to the current route automatically.

​
See also