Create Your First Audience

Audiences and contacts are two of the most fundamental parts of marketing on Mailchimp. A contact is an individual name and email address (amongst other information); audiences are lists of contacts to which you send campaigns. After signing up for an account, most new Mailchimp users start their marketing journey by creating an audience and adding contacts to that list; with the Marketing API, you can do the same things programmatically.

This guide will focus on two endpoints: Audience/Lists and Members. The Audience/Lists endpoint lets you create and manage your audiences. The Members endpoint lets you manage the contacts in those lists—creating, updating, deleting, and archiving—so you can integrate your users with your Mailchimp account.

You can use these endpoints to do things like:

• Create a new audience in response to events happening in your application

• Update contacts based on changes in your application

• Sync contacts from Mailchimp to your application

For the purposes of this guide, we run an events app. When a user creates an event, the app automatically creates a new audience for that event in Mailchimp. When attendees RSVP to the event, they can opt-in to receive messages from the event’s organizers, and when they do, they’re added to the corresponding audience. 

In this guide, we’ll use the Lists endpoint to create an audience associated with a new event: a JavaScript developer meetup. We’ll then use the Members endpoint to add one of our attendees to our audience, change their subscription status, verify that change, and ultimately delete the contact.

• A Mailchimp account

• Your API key and server prefix

Our events app is feature complete: authenticated users can create events and publish them, and other users can indicate that they plan to attend those events as well as their interest in recurring event series. Now we want to integrate with the Marketing API so that when an event is created, a corresponding audience is created in Mailchimp. 

Here, the audience we’re creating is users who want to attend our JS developers meetup:

#!/bin/bash
set -euo pipefail


event_name="Bash Developers Meetup"

footer_contact_info='{
  "company": "Mailchimp",
  "address1": "405 N Angier Ave NE",
  "city": "Atlanta",
  "state": "GA",
  "zip": "30308",
  "country": "US"
}'

campaign_defaults='{
  "from_name": "Gettin'\'' Together",
  "from_email": "gettintogether@example.com",
  "subject": "Bash Developers Meetup",
  "language": "EN_US"
}'

curl -sS --request POST \
  --url "https://$API_SERVER.api.mailchimp.com/3.0/lists" \
  --user "key:$API_KEY" \
  --header 'content-type: application/json' \
  --data @- \
<<EOF | jq '.id'
{
  "name": "$event_name",
  "contact": $footer_contact_info,
  "permission_reminder": "permission_reminder",
  "email_type_option": true,
  "campaign_defaults": $campaign_defaults
}
EOF

An audience is nothing without members. As our JS developer meetup approaches, people are using the app to RSVP. Prudence McVankab, a budding frontend developer, is among them.

In Mailchimp, a contact only exists in the context of the audience it’s a member of. You can’t create a contact and then later add that contact to a list—which means contacts can’t be explicitly shared between more than one list.

Since Prudence agreed to receive notifications about this meetup—as well as future developer events—when she RSVPed, we’ll add her as a contact to the audience we’ve just created.

To add a contact to an audience, you must include the subscription status in your payload:

• Use subscribed to immediately add a contact.

• Use pending to send a confirmation email. Once confirmed, the contact’s status will update to subscribed.

To add Prudence as a subscribed contact, do the following:

#!/bin/bash
set -euo pipefail


list_id="YOUR_LIST_ID"
user_email="prudence.mcvankab@example.com"
user_fname="Prudence"
user_lname="McVankab"

curl -sS --request POST \
  --url "https://$API_SERVER.api.mailchimp.com/3.0/lists/$list_id/members" \
  --user "key:$API_KEY" \
  --header 'content-type: application/json' \
  --data @- \
<<EOF | jq '.id'
{
  "email_address": "$user_email",
  "status": "subscribed",
  "merge_fields": {
	"FNAME": "$user_fname",
	"LNAME": "$user_lname"
  }
}
EOF

The id returned in the response will be an MD5 hash of the contact’s lowercase email address. You can learn more about that here.

Let’s verify that we successfully added Prudence to our audience by checking her subscription status:

#!/bin/bash
set -euo pipefail


list_id="YOUR_LIST_ID"
email="prudence.mcvankab@example.com"

subscriber_hash=$(echo -n "$email" | md5sum | cut -f1 -d' ')

curl -sS --request GET \
  --url "https://$API_SERVER.api.mailchimp.com/3.0/lists/$list_id/members/$subscriber_hash" \
  --user "key:$API_KEY" \
| jq '.status'

Check a contact’s subscription status

If the call returns an error response, the contact is not on the list.

If the call returns successfully, check the status field. You should see one of the following labels: 

Since we just added Prudence as a contact with a status of subscribed, we should expect to see that status reflected in the response.

Prudence has loved our JS developer meetups, but when she gets a job in another city, she no longer needs to receive our emails. She’s logged into the app and indicated that she is no longer interested in our meetups; now we need to unsubscribe her contact from the corresponding audience in Mailchimp.

#!/bin/bash
set -euo pipefail


list_id="YOUR_LIST_ID"
email="prudence.mcvankab@example.com"

subscriber_hash=$(echo -n "$email" | md5sum | cut -f1 -d' ')

curl -sS --request PUT \
  --url "https://$API_SERVER.api.mailchimp.com/3.0/lists/$list_id/members/$subscriber_hash" \
  --user "key:$API_KEY" \
  --header 'content-type: application/json' \
  --data @- \
<<EOF | jq '.status'
{
  "status": "unsubscribed"
}
EOF

• Marketing Fundamentals

• Organize Contacts with Tags

• Audiences/Lists API Reference