Skip to main content
A List is a group of users you maintain in SuprSend to notify as a single audience — for example, everyone who signed up in the last 30 days. You can send a one-off broadcast to the entire list, or trigger a workflow for individual users as they enter or exit the list — a welcome flow when someone joins, or a win-back flow when they drop off. Every workspace gets an all_users list by default, which contains every user in the workspace. Use it for newsletters and product-wide announcements.

​
How it works

You put users into a list once, and then use the list two ways: send a broadcast to everyone in it, or trigger workflows when users enter or leave.

​
Creating lists

You can create a list via the + New List button on the dashboard, or via the Create List API. In the create-list modal, set a list_id (required — unique within the workspace; lowercase letters, digits, and underscores only), plus an optional display name and description.
New List modal with list_id, name, and description fields
Then choose how you’d want to sync users into the list:

Segment List

Filter users by their properties or the events they’ve performed — for example, users on the Growth plan who haven’t logged in for 30 days. Membership keeps itself up to date: users join the list the moment they meet the criteria and drop off as soon as they no longer qualify.

Database sync

Connect your data warehouse and sync users by writing a SQL query. It can also create users who don’t yet exist in SuprSend and sync additional user properties you’d want to reference in a broadcast or workflow as $recipient.<key>.

CSV upload

Upload a fixed set of known users from the dashboard — a snapshot you re-upload to refresh. Good for one-off campaigns with no engineering involvement.

SDK / API

Add and remove users in real time from your backend, using an SDK (Node, Python, Java, Go) or the HTTP API directly.

Third-party sync

Pull cohorts already defined in an analytics tool like Mixpanel through a connector — no SQL required.
To build an audience from a rule like “Enterprise users in the US with 3+ orders in the last 60 days”, use a Segment List if those properties and events are already synced into SuprSend, or database sync if that data lives outside SuprSend in your data warehouse. For a fixed set of IDs you already have, a CSV upload is simplest.

​
Sending notifications to list users

Two paths, depending on whether you’re firing on membership change or sending to the whole list at once.
  • Broadcast — the recommended way to send to a whole list. Schedule from the dashboard with Run Broadcast, or trigger via the Broadcast API. Use a promotional preference category so the send doesn’t compete with transactional traffic; see choosing a preference category.
  • Workflow on list entry / exit — fire a workflow when a user joins or leaves the list, e.g. re-engaging job seekers who dropped out of “active in the last 7 days.” Set this up in the workflow itself: add a List entry / exit trigger node and select the list. The $USER_ENTERED_LIST / $USER_EXITED_LIST events then fire automatically as users join or leave — which in turn triggers the workflow.
Avoid triggering individual workflows on a single list update that touches more than 1,000 users at once — it can back up your notification queue. For bulk sends, use a broadcast.

​
Lists vs Objects

Both group recipients together, but they’re different kinds of things.
  • A List is simply a group of users you notify in bulk.
  • An Object is an entity in its own right — with its own properties, channels, and preferences — that users subscribe to.
  • Reach for a List when you already know the set of users to send to; reach for an Object when you know the group a workflow should target but not the individual users, which makes objects a natural fit for modeling company or team structure (e.g. a team’s #devs Slack channel).

​
FAQ

Most likely the workflow was created after those users were added, so they don’t count as new entries — list entry/exit events only fire for users who join or leave after the workflow’s trigger node is active. Add the users again, or run a broadcast to reach existing members.
No. CSV upload only maps existing users to the list. Identify users first via the SDK or API, then upload the CSV.
Deletion is blocked while a workflow or scheduled broadcast references the list. Remove those references first.
Unique within the workspace, lowercase letters, digits, and underscores only. It’s the stable identifier you’ll pass to the API and reference from workflows.
Use a dynamic list. Segment Lists query your live users and events data; database sync refreshes from your warehouse on a schedule; the SDK lets you keep it up to date in real time from your backend.