Create Your First Audience

At a glance

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 Malichimp 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.

Create an audience

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. 

Note: This guide uses “list” and “audience” somewhat interchangeably. Within the context of the Mailchimp UI, “audience” is more common, but the API endpoint to create an audience is lists.  Similarly, “member” and “contact” are used interchangeably. Again, “contact” is more common in the UI, but “member” is more often referenced in the API.

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

Create an audience

#!/bin/bash
set -euo pipefail


event_name="Bash Developers Meetup"

footer_contact_info='{
  "company": "Mailchimp",
  "address1": "675 Ponce de Leon Ave NE",
  "address2": "Suite 5000",
  "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

Add a contact to an audience

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:

Add a contact to an audience

#!/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.

Note: If you’re not sure whether or not a contact has already been added to an audience, you should use the Add or update a list member endpoint. This will create the contact if it doesn’t already exist, or update a contact’s information if it does.

Check a contact’s subscription status

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

Check a contact’s 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'

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: 

  • subscribed: The contact is already subscribed to the list and can receive campaigns. Note that campaigns can only be sent to subscribed contacts.

  • unsubscribed: The contact is no longer subscribed to the list.

  • pending: The contact requested to be added to the list with double-opt-in, but has not yet confirmed their subscription.

  • cleaned: The contact bounced and was removed from the list.

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

Unsubscribe a contact from your audience

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.

Unsubscribe a contact from your audience

#!/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

Note: Although you could also set a user’s status to cleaned, which will unsubscribe that user from your list, that status is reserved for contacts who shouldn’t receive email because their mail was bouncing. Most often, the cleaned status should be set organically by Mailchimp, and you should use unsubscribed.