Audiences

The lists this mailbox groups its contacts into. Every mailbox has a default audience holding every contact, and may define more: a newsletter list, the people at one customer, whoever came in from a form. Listing them sends nothing; sendToAudience sends one email to everybody in one. One page at a time: when more follow, the last line gives a cursor to pass back for the next page. Anybody but the workspace owner sees the default audience and the audiences they created, and only the contacts they added.

One audience in full: its name, what it is for, how many contacts are in it and whether it is the default one. listAudienceContacts is what lists who is actually in it.

Create an audience: a named list this mailbox’s contacts can be put in. It is created empty, and addContactToAudience fills it. Nothing stops two audiences sharing a name, so read listAudiences first rather than making a second “Newsletter” beside the one that is already there. Creating one sends nothing; sendToAudience is how an email goes to everybody in it.

Rename an audience or change what it says it is for. Passing null clears the description. The default audience can be renamed like any other, because the name is just this mailbox’s word for “everyone”, but it stays the default whatever it is called.

Delete an audience. The audience and its membership go; every contact that was in it stays, and keeps its notes. This is permanent and nothing here recreates the membership. The default audience cannot be deleted.

Who is in one audience, with the date each person joined it. Same shape as listContacts, narrowed to one list, and paged the same way: pass the cursor from the last line back, with the same sort and filters, for the next page. q searches the name and the address, source separates the ones added by hand from the ones recorded from a send, and sort orders the list the way the audience page can: last-heard-newest (the default), last-heard-oldest, added-newest, added-oldest or name. statuses keeps only subscribed or only unsubscribed members; leave it out, or name both, for everyone. Asking for the default audience lists every contact on the mailbox. Walking every page is how to export a list.

Put an existing contact in an audience. The contact has to exist already: this never creates one, because a mistyped address would become a permanent row nobody asked for. createContact adds it first. Adding somebody to a list sends nothing to them.

Take a contact out of an audience. The contact stays a contact on this mailbox, with its notes and its other audiences. Nobody can be taken out of the default audience, which holds every contact there is; deleteContact is what removes somebody from the mailbox entirely.

Put up to 200 existing contacts in one audience in one call, by address. Like addContactToAudience it never creates a contact: an address that is not a contact yet is listed back as not added, and importContactsToAudience is the call that creates them. Somebody already in the audience is left as they are. Adding people to a list sends nothing to them.

Take up to 200 contacts out of one audience in one call, by address. Every one of them stays a contact on this mailbox, with its notes and its other audiences. Addresses that are not in the audience, or are not contacts at all, are listed back and nothing happens to them. Nobody can be taken out of the default audience; deleteContact removes somebody from the mailbox entirely.

Bring a list of people into an audience, creating the contacts that do not exist yet, the way importing a CSV on the audience page does. Up to 500 rows per call; send a longer list in further calls. An address that is already a contact is reused, never duplicated, and keeps the name it has; a name given here only fills one that was empty. Every new contact also joins the default audience. Malformed addresses are skipped and listed back. Nothing is sent and nobody is subscribed to anything. A row can carry custom fields as attributes, such as the other columns of a spreadsheet: each value replaces the field of that name and the fields a row leaves out keep their values. Anybody but the workspace owner cannot touch a contact another member added, and those rows are skipped.

Take every contact out of one audience at once. The audience stays, empty, with its name and description, and every contact stays a contact with its notes and its other audiences. This cannot be undone and nothing records who was in it, so read listAudienceContacts first if the list matters. The default audience cannot be emptied, because it holds every contact for as long as it is a contact. Anybody but the workspace owner only takes out the contacts they added.

Say exactly which audiences one contact is in, in one call: it joins every audience listed and leaves every other one. The default audience is kept whatever is passed, because every contact is in it, so an empty list takes the contact out of every audience but that one. The contact has to exist already; createContact makes it. An audience id that does not exist is refused and nothing changes. Moving somebody between lists sends nothing to them. Anybody but the workspace owner can only move the contacts they added, and audiences they cannot see are left as they are.

How audiences have grown: how many contacts joined each list over a window that ends now, bucketed by day, hour or minute, the chart on the audiences page. Pass audienceIds for some lists or leave it out for every audience; days reaches back from 1 to 1095 (30 by default), and minutes sets a shorter window, such as the last hour by minute, and wins over days. offsetMinutes is the reader's UTC offset, so days break at their midnight. An audience only records when somebody joined, never when they left, so every figure counts the people still in the list today by the date they joined, and it never falls. Contacts counts each person once however many lists they are in, while Memberships adds the lists up. Anybody but the workspace owner reads the default audience and the audiences they created, and the figures count everybody in those lists.