Audience

Audience is the one list of everyone Arc CMS can email: each person is a contact, grouped into lists, labelled with tags and carrying custom fields and their marketing consent. Sign-ups, signup forms, payments and imports feed it on their own.

What it is

A contact is one email address. The same address is always the same contact, however many forms, lists or imports it came through. Everything else hangs off the contact:

Contacts decide who may get marketing email. Sending itself (providers, templates, logs, the unsubscribe link) is the Email engine. Broadcasts and sequences are Email marketing. Forms that collect contacts are Signup forms.

Turn it on or off

The feature id is audience. It is on by default. Signup forms (forms) and email marketing (email-marketing) need it, so turning it off means turning those off too, in src/custom/features.ts:

export const CUSTOM_FEATURES: FeatureChoice = {
    off: ['audience', 'forms', 'email-marketing'],
};

Leaving forms or email-marketing on without audience stops npm run dev and npm run build with a message saying what to change.

When it is off:

• The Audience menu, its pages and the Settings, App audience tab are gone. Their addresses show the not-found page.
• The functions in functions/src/features/audience.ts are not built, so the next deploy of all functions removes them. New users, form sign-ups and payments do not create contacts.
• Email ignores contacts: a contact's consent or disabled switch does not block a send. An unsubscribe still stops marketing email through the Suppression list.
• The data stays. Turn the feature back on, build and deploy, and it all comes back.

See Feature ids for every feature, and Choose your app's features for choosing them in an app.

Set it up

A fresh install needs nothing: the first sign-up creates the first contact and the All Users list. On an install that already has users or form sign-ups from before the audience existed, build the audience from them once:

1. Open Audience, Contacts and click Backfill. It makes a contact for every user (and joins paying ones to All Customers), for every verified form member, and a pending contact for every unverified form member. It is safe to run again.

2. Open Audience, Lists and click Sync form lists. It creates the list of any signup form that has none.

3. If your forms carried their own tags, open Audience, Tags and click Import waitlist tags. If forms collected extra answers, open Audience, Fields and click Import past form data after creating the fields.

To send email at all, set up a provider first: see Email engine.

Use it

How people become contacts

Consent is set only when a contact is first created. A returning address keeps the consent it has: someone who unsubscribed stays unsubscribed when they join a second form. Deleting a user takes their contact off All Users and All Customers but keeps the contact.

Consent

Transactional email (a sign-in code, a receipt) ignores consent. The counts at the top of the Contacts page filter the table by consent when clicked.

Import contacts from a CSV

1. On Audience, Contacts click Import CSV and paste the file. Each row is email or email,name. A header row is optional.

2. Click Preview. It counts valid rows, rows with a bad address and addresses repeated in the file. Nothing is written yet.

3. Choose the list to add them to. Tick the consent box only if these people agreed to marketing email, then import.

Lists

Click a list to open its page. It has three tabs: Members, Broadcasts sent to it, and its Sequence (the last two need Email marketing). On a form's list, members cannot be removed, because the form decides who is in it. Use Disable emails on a member instead.

Tags

Create a tag on Audience, Tags with a label and a color. Its id is the label in lowercase with dashes (VIP Customer becomes vip-customer), so two admins adding "VIP" get one tag. Put tags on a contact in the contact's panel; changes save at once. Filter the Contacts table by tag to see everyone carrying it. Deleting a tag takes it off every contact. A signup form can give every new member a default tag: see Signup forms.

Sends target lists, not tags. To email everyone with a tag, add them to a list.

Custom fields

Create a field on Audience, Fields:

Use a field in any email as ##FIELD:company##, or with an inline fallback as ##FIELD:company|your company##. Values arrive from form answers mapped to the field (see Signup forms) or from an admin editing the contact's panel, which always overwrites. Deleting a field keeps the values already on contacts; creating it again shows them again. All merge tags are listed in Email merge tags.

Stop emailing someone

Three actions look alike and are not interchangeable. Suppress and Erase are in the contact's panel on the Contacts page; Disable is on a list's page:

Extend it

Your own Cloud Functions in functions/src/custom/ can add people to the audience with the same helpers core uses, from functions/src/email-core/contacts.ts. Check that the feature is on first:

import { isFeatureOn } from '../feature-flags.js';
import { upsertContact, removeContactFromLists } from '../email-core/contacts.js';

if (isFeatureOn('audience')) {
    // Creates the contact if new, then joins the lists (and their active sequences).
    // A list's id is the last part of its page address, /admin/lists/{listId}.
    await upsertContact({ email, name, source: 'manual', addLists: [BETA_LIST_ID] });
}

Always join and leave lists through upsertContact, addContactToLists and removeContactFromLists. They keep each list's member count right and start or end that list's sequences. Writing a contact's listIds yourself skips both.

Without code, an automation rule can add or remove people on lists when an event happens: see Automations. To use your own app's users without copying them, see App audience.

What it stores

Every collection is also in Data model. App audience state (AppAudience) is described in App audience. The feature uses no Storage paths.

Cloud Functions (each deploys as arccms- followed by its name; see Cloud Functions):

Who can do what

Only Cloud Functions write contacts. Every callable above refuses anyone without the admin role (the arccms_role claim); see Roles and claims. Visitors and members never read the audience.

Troubleshooting