Audiences
Named lists the contacts are grouped into.
Audiences tools
| Tool | What it does |
|---|---|
| listAudiences | The lists this mailbox groups its contacts into, the default one first. An audience is a grouping and nothing else. |
| getAudience | One audience in full: its name, what it is for, how many contacts are in it and whether it is the default one. |
| createAudience | Create a named list. It is created empty, and nothing stops two audiences sharing a name, so read the list first. |
| updateAudience | Rename an audience or change what it says it is for. The default audience can be renamed like any other and stays the default whatever it is called. |
| deleteAudience | Delete an audience. The membership goes, every contact that was in it stays. The default audience cannot be deleted. |
| listAudienceContacts | Who is in one audience. Asking for the default audience lists every contact on the mailbox. |
| addContactToAudience | Put an existing contact in an audience. It never creates a contact, because a mistyped address would become a permanent row nobody asked for. |
| removeContactFromAudience | Take a contact out of an audience. It stays a contact, with its notes and its other audiences. |
Every mailbox has a default audience holding every contact, and it is the one thing here that cannot be deleted or thinned. Taking somebody out of it would mean a contact that listContacts shows and listAudienceContacts cannot, which is a book that disagrees with itself. deleteContact is what removes somebody from the mailbox entirely.
Nothing here sends to an audience, and there is no tool that does. An audience is a way of grouping contacts, not a subscription list, and putting somebody in one mails them nothing.
Adding a contact to a list is a write to the LIST rather than to the contact, so it is gated on audiences:write and not on contacts:write. Reading the addresses in an audience needs only audiences:read.