Skip to navigation

Audiences

The basics

An audience is a list of contacts. Almost everything you do with the Marketing API happens inside one: contacts belong to an audience, and so do the merge fields that describe them and the segments that group them.

Most integrations work against an audience that already exists. You’ll need its list_id, which you can find with GET /3.0/lists.

How the pieces fit together

Audience
├── Contacts            people, identified by email address
│   ├── Tags            labels you apply to individual contacts
│   └── Merge field values
├── Merge fields        the field definitions for this audience
└── Segments            saved queries that select contacts
Each contact also carries consent, recorded separately per channel
(email, SMS).

Contacts are the people in an audience. Each one is identified by their email address, and in the API by the MD5 hash of that address in lowercase — the subscriber_hash you’ll see throughout the endpoints.

Tags are labels you attach to individual contacts. They’re yours to define: map them from your CRM, or use them to record behavior that matters to you. Tags live on the contact, not on the audience.

Merge fields are the custom data fields an audience can store about its contacts — first name, birthday, favorite product. The definitions belong to the audience; the values belong to each contact. That split is the part people trip over: adding a merge field to an audience doesn’t populate it, and setting a value on a contact requires the field to exist first.

Segments are saved queries that select a subset of contacts, using conditions like signup date, campaign engagement, or which tags a contact carries. A segment doesn’t contain contacts or tags; it selects contacts, and the set changes as your data does.

Tags versus segments: a tag is something you put on a contact. A segment is a question you ask about contacts. Tags are one of the things a segment can filter on, which is why they’re easy to confuse.

Consent is the record of what a contact agreed to receive from you, and it belongs to the contact rather than to the audience. Mailchimp tracks it per channel: agreeing to marketing email says nothing about agreeing to marketing SMS, and the two are stored and updated independently.

Consent is an input, not the final answer to “can I send to this person?” What Mailchimp sends on is a subscription status, which it derives from the consent you supply, the audience’s opt-in configuration, and whether the contact is reachable on that channel at all. A contact who consented to email can still stop receiving it because their address started bouncing. You record consent; Mailchimp decides deliverability.

That split is the part integrations get wrong. Writing a contact through the API is a consent event, so the value you send has to reflect something the person actually did. If your checkout form has a marketing checkbox, the state of that checkbox is your consent record. Sending every customer through as opted in because they bought something is the failure mode to avoid.

Why this matters

Email and SMS marketing are regulated—GDPR, CAN-SPAM, CASL, and TCPA among others—and the obligations attach to you as the sender, not to Mailchimp as the platform. Consent is the evidence that you met them, which is why the API asks you to state it explicitly rather than inferring it.

SMS carries the stricter rules of the two. Consent to email does not extend to SMS under any regime we know of, and several require separate, provable opt-in for messages sent to a phone. Treat the two channels as genuinely separate records, because that is what they are.

Which endpoint you use to record consent depends on the channel, and the mechanics differ between them. See Contacts for the contact-level model and Audiences endpoints (beta) for the SMS channel.

Where to go next