A *service case study: Accessing your Mailchimp account from a GuidedTrack program

If you use Mailchimp to manage your mailing lists, you can access it from your GuidedTrack program using *service. This means that when someone running your program gives you their email address, you can automatically add it to your Mailchimp audience. Additionally, you can access subscribers’ information and update it based on the program they use or the data they enter into it.

In this case study, you will learn to:

  • Create and configure the service in your program settings.
  • Retrieve a subscriber’s id and status.
  • Add a new subscriber to your list.
  • Update an existing subscriber.

In order to get started, there are a couple of things you will need to retrieve from your Mailchimp account: an API Key and  the unique ID of your audience.

Getting a Mailchimp API Key
  1. Log into Mailchimp, click on your name in the top right and select Account from the drop down.
  2. Click Extras, then select API Keys from the drop-down menu.
  3. Create a key or copy an existing one.
Finding your audience’s unique ID
  1. Navigate to Audience on the upper bar.
  2. Click on Manage Audience, then select Settings.
  3. Find the ID at the bottom of the page under the text “Unique id for audience <your account name>”

Now it’s time to log into GuidedTrack and start working on your program!

How to create the Mailchimp service

From the editor window of your program, go into Settings, click Services, then New Service. Fill in the fields as shown:

name: mailchimp
URL: https://us7.api.mailchimp.com/3.0
username: anystring
password: <your API key here>

Make sure that the URL is pointing at the data center of your Mailchimp account (the bold prefix). You can identify your data center by looking at the last characters of your API key (-usXX)

Once you are done, click “Save” and start editing your program.

Retrieving a subscriber’s ID and status

This is useful if you want to check if an email address is already in your audience or to retrieve the data linked to an existing one. We have created a program for you that is ready to use, or you can check out the code to customize it to fit your needs. If you choose to use the program we created, paste in your program the following lines of code:

>>in_email = “WolfgangAMozart@greatmusic.com”
>>in_subscriberListID = “your audience’s unique ID“

*program: mailchimp – lookup email – public

These are the variables that the program returns:

  • out_mailchimpResponse: Full response from mailchimp
  • out_userFound: 1 if the email is already in the audience, 0 if it is not
  • out_userData: An association with all the data linked to the user
  • out_userID: Unique ID of the email address
  • out_userStatus: “Subscribed”, “Unsuscribed”, …

If an error occurs when accessing Mailchimp, its description will be stored in the variable out_error and its code will show in out_errorCode.

Adding a new email to your audience

The program we have created allows you to add a new subscriber’s email address to your mailing list, and optionally assign it one of your “interests” or set the value of the Merge Fields of your choice. You can look at the code to use it as a guide to create your own, or simply add these lines to your program:

>>in_email = “WolfgangAMozart@greatmusic.com”
>>in_subscriberListID = “your audience’s unique ID“

*program: mailchimp – add new email – public

If you want to assign one of your “interests” to the new subscriber, you will need to have its ID. You can find it logging into the Mailchimp API playground with your API key. Then follow these steps:

  1. Go to Lists
  2. On your audience, click on Subresources and choose interest-categories
  3. On the category that the interest is, click on Subresources and choose interests
  4. Click on the desired interest and you will find the ID in the field called id

The code to add to your program will now be:

>>in_email = “WolfgangAMozart@greatmusic.com”
>>in_subscriberListID = “your audience’s unique ID“
>in_interestID = “the interest ID“>

*program: mailchimp – add new email – public

If you want to set the value of certain Merge Fields, you will need to create an association linking the Merge Tag to its desired value:

>>in_email = “WolfgangAMozart@greatmusic.com”
>>in_subscriberListID = “your audience’s unique ID“
>>in_mailchimpMergeFields = {“FNAME”->”Wolfgang”, “LNAME”->”Mozart”}

*program: mailchimp – add new email – public

Updating an existing subscriber

The program to update the data of a subscriber that is already on your list requires that you identify the subscriber by their ID. It is likely that you will have their email available, but not the ID -if this is the case, you can use the program “mailchimp – lookup email – public” to retrieve it! You can assign a new interest to a subscriber and set the value of Merge Fields:

>>in_userID = “kdkdk3k3303u92733fjdj3333jd”
>>in_subscriberListID = “your audience’s unique ID“
>>in_mailchimpMergeFields = {“FNAME”->”Wolfgang”, “LNAME”->”Mozart”}

*program: mailchimp – update subscriber – public