Audiences

An audience is a named group of contacts in a project, for example "Beta testers" or "Monthly changelog". A contact can be in any number of audiences. A broadcast goes to exactly one audience.

Create an audienceCopy Anchor Link

const audience = await flaresend.audiences.create({ name: 'Beta testers' });
// { id: 'aud_01K6B4F7...', name: 'Beta testers', contactCount: 0, ... }

Names are 1–200 characters and must be unique within the project. A second audience with the same name fails with 409 audience_exists.

Add and remove contactsCopy Anchor Link

Audiences hold contact IDs. Create or import the contacts first, then add their IDs, up to 5,000 per call:

const ada = await flaresend.contacts.create({ email: 'ada@example.com', firstName: 'Ada' });
const grace = await flaresend.contacts.create({ email: 'grace@example.com', firstName: 'Grace' });

const { added } = await flaresend.audiences.addContacts(audience.id, [ada.id, grace.id]);

• Adding a contact that is already in the audience does nothing, and doesn't count in added.
• If any ID is not a contact in this project, the whole call fails with 404 contact_not_found and nothing is added.

Removing works the same way and returns { removed }:

await flaresend.audiences.removeContacts(audience.id, [grace.id]);

In the dashboard, open an audience and use Add contacts to search and pick contacts, or select members to remove them in bulk.

List membersCopy Anchor Link

const { data, nextCursor } = await flaresend.audiences.contacts(audience.id, { limit: 100 });

Members come back newest contact first, paginated. The list includes unsubscribed contacts; broadcasts skip them when sending.

contactCount on the audience counts every member, subscribed or not.

Rename or deleteCopy Anchor Link

await flaresend.audiences.update(audience.id, { name: 'Beta testers (2026)' });
await flaresend.audiences.remove(audience.id);

Deleting an audience removes the list, not the contacts in it. It fails with 409 audience_in_use while a broadcast to it is scheduled or sending; cancel the broadcast first.

APICopy Anchor Link