Mailchimp Developer LogoMailchimp Developer Wordmark
Skip navigation

Mailchimp Marketing API

Manage Contacts and Events with the Mobile SDK

At a glance

Unlike the client libraries, the Mailchimp Mobile SDK implements a mobile-oriented subset of Mailchimp’s Marketing API, providing mobile developers an easier path to integrating with core functionality most relevant to mobile devices. This guide covers both types of data that the Mobile SDK can manipulate—contacts and events.

You can use the Mobile SDK to do things like:

  • Add contacts to an audience when they sign in to your mobile app

  • Update contacts based on changes in your app

  • Log events such as launching your app, viewing an item, or leaving a rating 

Before getting started with this guide, make sure you’ve added the Mobile SDK to your app. The easiest way to do this is through a dependency manager, such as Cocoapods for iOS apps or Gradle for Android apps. Check out the docs for further details and step-by-step instructions. 

For the purposes of this guide, we run an app for a chain of cafés called You Win Some, You Brew Some. We’ll follow a new customer after she downloads our app: adding her as a contact, tagging her contact with location data, and logging her app activity with events, which we’ll use to offer her discounts on future purchases. 

What you’ll need

  • An audience in your Mailchimp account

  • The Mobile SDK key for your chosen audience

  • Your iOS or Android app, including the Mobile SDK

Set up the SDK for your audience

While the Marketing API has one key for each API user, the Mobile SDK has different keys for each of your audiences. You can retrieve the Mobile SDK key for any of your audiences in the Your API Keys section of your Mailchimp account.

When you initialize the Mobile SDK in your code, the Mobile SDK key is the only required piece of information, but there are also two optional parameters: debug mode and auto-tagging. In this guide, we’ll leave debug mode off and keep auto-tagging enabled, which will give us the standard logging behavior and add device information to our new contacts. 

Since these are both default settings, we don’t have to include them in our initialization code:

Initialize the Mobile SDK

val sdkKey = "YOUR_SDK_KEY"
val configuration = MailchimpSdkConfiguration.Builder(context, sdkKey)
.build()

Add a contact

Esther McVankab is new to You Win Some, You Brew Some, and we want to add her as a contact. We know her name and email address, and based on her phone’s location settings, we can see that she’s near Athens, Georgia. 

Let’s create a contact with her basic info and tag that contact with our Athens café location:

Add a contact

val newContact = Contact.Builder("esther.mcvankab@example.com")
    .setMergeField("FNAME", "Esther")
    .setMergeField("LNAME", "McVankab")
    .setContactStatus(ContactStatus.SUBSCRIBED)
    .addTag("athens-cafe")
    .build()
val sdk = Mailchimp.sharedInstance()
sdk.createOrUpdateContact(newContact)

Note: By default, the Mobile SDK automatically tags each newly created contact with their device platform (iOS or Android) and type (Phone or Tablet). You can disable this feature when you initialize the SDK within your app.

Update a contact with new information

When Esther places her first coffee bean order, she asks that it be delivered to an address in Atlanta. We’ll add the delivery address to her contact, and based on this new location information, we’ll add a tag so we can include her in campaigns about our Atlanta outpost: 

Update a contact

val address = Address.Builder("123 Chimp St.", "Atlanta", "30308")
		.setState("GA")
		.setCountry(Country.USA)
		.build()
val newContact = Contact.Builder("esther.mcvankab@example.com")
    .setMergeField("ADDRESS", address)
    .addTag("atlanta-cafe")
    .build()
val sdk = Mailchimp.sharedInstance()
sdk.createOrUpdateContact(newContact)

Add events based on contact activity

To keep our customers at You Win Some, You Brew Some engaged, we want to know how often they’re launching our app. The Mobile SDK lets us track this activity by logging events, and we can use those events to segment our audience and set up automations—for example, a discount code after a period of inactivity. 

Each time that Esther used our app previously, we associated her contact with an event:

Add an event

val sdk = Mailchimp.sharedInstance()
val eventProperties = mapOf("source" to "Android")
sdk.addContactEvent("esther.mcvankab@example.com", "app-launched", eventProperties)

Based on our event log, it’s been two weeks since Esther last opened the app. Combining this information with the atlanta-cafe tag on her contact, we can generate a specifically targeted email, offering her a discount on her next purchase at the Atlanta location. For more on event-based automations, see the events guide.

More resources