Check your version

This video covers a topic in Drupal 7 which may or may not be the version you're using. We're keeping this tutorial online as a courtesy to users of Drupal 7, but we consider it archived.

Collect Additional Information with Merge Fields

Video loading...

  • 0:02
    Using MailChimp with Drupal 7
  • 0:04
    Collect Additional Information with Merge Fields Series Sponsored by MailChimp
  • 0:09
    MailChimp allows you to collect additional information
  • 0:12
    about contacts that are subscribed to a list.
  • 0:14
    In our example application, where we're creating a website
  • 0:17
    for a set of ice cream stores,
  • 0:20
    it might be useful to collect some additional information
  • 0:23
    for our mailing list, like the user's first and last name, for starters.
  • 0:26
    But also things like maybe their birthday
  • 0:28
    so we can send them a coupon on their birthday.
  • 0:30
    And maybe the city that they live in or their location,
  • 0:33
    which store is closest to them,
  • 0:35
    so that when we send them updates
  • 0:37
    we can also send them updates that are specific to a store.
  • 0:40
    There's lots of reasons that we might want to collect additional information
  • 0:43
    and put that into MailChimp.
  • 0:45
    With that additional information,
  • 0:48
    MailChimp can do things like segment our list
  • 0:50
    so that rather than send to the entire list,
  • 0:53
    you only send to a subset of the users on the list.
  • 0:56
    Similar to Drupal's Field UI,
  • 0:58
    you can add any number of new data points,
  • 1:00
    called merge fields, to a contact in MailChimp.
  • 1:03
    In this tutorial, we'll look at how to configure
  • 1:06
    merge fields in the MailChimp UI
  • 1:08
    and then demonstrate how to synchronize the value of a field in Drupal
  • 1:12
    with the MailChimp merge field.
  • 1:14
    This will allow us to create first and last name fields in Drupal
  • 1:17
    that keep the contact's information
  • 1:19
    up to date in MailChimp
  • 1:21
    by synchronizing that data whenever it's changed.
  • 1:24
    We'll look at doing this both for simple text fields,
  • 1:27
    like first and last name, and for more complicated fields,
  • 1:30
    like a date field with a birthday in it,
  • 1:32
    and a vocabulary or term reference field
  • 1:36
    that can have multiple values.
  • 1:38
    I'm assuming you've already got a MailChimp mailing list set up
  • 1:42
    and understand how to synchronize
  • 1:45
    the subscription of an entity
  • 1:47
    to a list in MailChimp using the MailChimp Lists module,
  • 1:50
    that you've got some basic familiarity with Drupal's field UI
  • 1:53
    and configuration and that you've also used
  • 1:56
    the Date module to create date fields before.
  • 2:00
    If you haven't, check out the links in the description
  • 2:02
    for this tutorial to videos that we have
  • 2:05
    that will help explain those concepts.
  • 2:08
    By the end of this tutorial, you should be able to add
  • 2:10
    additional merge fields to a MailChimp list
  • 2:12
    and keep the content of those fields
  • 2:14
    in sync with fields from a Drupal user account.
  • 2:18
    Let's go ahead and get started.
  • 2:20
    I'll start by showing the setup I've currently got on the Drupal side of things.
  • 2:23
    If I go to Configuration
  • 2:25
    and then Account settings
  • 2:27
    and Manage Fields,
  • 2:29
    you can see that I've added a number of different fields
  • 2:32
    to my Drupal user entity.
  • 2:34
    I've got a first and last name field,
  • 2:36
    both of which are simple text fields.
  • 2:38
    I've got a birthday field that was created
  • 2:40
    using the Date Module, which allows for a select list
  • 2:43
    where someone can choose the month, day and year
  • 2:45
    of their birthday.
  • 2:47
    And then I've got a Locations field, which is a term reference field
  • 2:50
    that references a vocabulary I created named Locations.
  • 2:54
    That vocabulary contains the locations
  • 2:56
    of the 3 stores that are part of our ice cream shop chain.
  • 2:59
    If I edit my account,
  • 3:02
    so I click on Hello Admin up here in the toolbar
  • 3:04
    and then click the Edit link for my profile,
  • 3:08
    this is what those fields look like.
  • 3:10
    We have a text field for first and last name.
  • 3:12
    Here's our birthday field, and then check boxes for locations.
  • 3:15
    Important to note, these are very different field types,
  • 3:18
    and the type of data they store is very different.
  • 3:20
    Simple text, a date field.
  • 3:22
    In our case, this is configured
  • 3:24
    to store the date as a Unix time stamp
  • 3:26
    based on whatever I enter into the select list.
  • 3:29
    And then locations, which you'll notice here
  • 3:31
    has 3 different check boxes,
  • 3:33
    so ostensibly this is a multi-value field.
  • 3:37
    So I could have multiple values.
  • 3:39
    It's also a term reference field, so I'm not actually entering any text here.
  • 3:42
    I'm entering a reference to another Drupal entity.
  • 3:46
    So keep that in mind as we go through.
  • 3:48
    Now what I want to do is switch over to the MailChimp UI.
  • 3:52
    Over on,
  • 3:54
    I'm going to edit our lists.
  • 3:56
    I'm going to go to Lists.
  • 3:58
    Then I'm going to go to Weekly Newsletter,
  • 4:01
    and for a list, once I'm on the main page for that list,
  • 4:05
    I can click on the Settings sub tab here
  • 4:08
    and then select List fields and Merge tags.
  • 4:13
    This is the user interface that MailChimp provides
  • 4:16
    in order to allow us to add additional merge fields.
  • 4:18
    There's two of them here already, first name and last name
  • 4:22
    and the required email address,
  • 4:24
    because you have to have an email address to subscribe to a mailing list.
  • 4:26
    First name and last name were added
  • 4:28
    when we first created the mailing list.
  • 4:30
    I'm going to add additional fields
  • 4:33
    for birthday and location.
  • 4:37
    I'm going to add a field for location first.
  • 4:40
    This one's going to be just a text field.
  • 4:43
    MailChimp doesn't have the same concept
  • 4:45
    of multi-value fields in the same way that Drupal does.
  • 4:49
    And so what we're going to demonstrate
  • 4:51
    is how you can create a text field in MailChimp,
  • 4:54
    and then on the Drupal side when we're synchronizing the data
  • 4:57
    from our term reference field, we can do so as a comma separated list of values
  • 5:01
    that MailChimp can still make sense of.
  • 5:04
    I added that field. I gave it a human readable name.
  • 5:07
    I can also change the tag name here
  • 5:11
    or leave it as the default that MailChimp gave me.
  • 5:14
    My recommendation is to change these
  • 5:16
    to something meaningful to you
  • 5:18
    because later, when you're creating templates for your emails,
  • 5:21
    and you'd like to put in this merge tag
  • 5:24
    into the body of the email and have it be replaced with, say,
  • 5:27
    the user's first name and last name,
  • 5:30
    it makes more sense if you can read, "Oh, this is the first name field,
  • 5:33
    this is the location field"
  • 5:35
    and not have to try to figure out what Merge3 or Merge6 means.
  • 5:38
    I'm also going to add another field
  • 5:41
    for birthday.
  • 5:43
    MailChimp has a specific field for adding birthdays
  • 5:47
    for collecting that data, so I'll click on the birthday field type.
  • 5:50
    I'll give it a label and text
  • 5:55
    or a merge tag name like so.
  • 5:57
    And then click Save Changes.
  • 5:59
    What we did was we recognized
  • 6:02
    that MailChimp already has 2 fields here,
  • 6:04
    first name and last name, that are simple text fields.
  • 6:06
    We added a new text field for locations
  • 6:08
    and then a new birthday field.
  • 6:11
    We changed the tag labels and saved that data.
  • 6:14
    One additional bit of information here
  • 6:16
    is the birthday field allows you to choose
  • 6:20
    the format for dates that are stored,
  • 6:22
    month/day or day/month.
  • 6:25
    We'll leave it as is like so.
  • 6:28
    Back on my Drupal site, I need to do a couple of things now.
  • 6:31
    First I need to go to Configuration
  • 6:34
    and then scroll down to MailChimp under Web Services
  • 6:38
    and then click on the Lists tab for MailChimp configuration
  • 6:41
    and click this Refresh Lists from MailChimp
  • 6:46
    and then Confirm.
  • 6:48
    Whenever Drupal retrieves information about our list from MailChimp
  • 6:50
    it caches it, and since we just added new merge fields
  • 6:53
    on the MailChimp side of things, we need to update
  • 6:56
    the cached metadata about the list in Drupal.
  • 6:58
    That's what clicking that link there does.
  • 7:00
    I'm also going to clear Drupal's cache, just for good measure.
  • 7:04
    I'm going to go to Configuration,
  • 7:06
    Performance and click Clear All Caches.
  • 7:10
    The reason I'm clicking Clear All Caches here
  • 7:12
    is because we've already got a MailChimp list field configured
  • 7:15
    for our Drupal user account,
  • 7:18
    and we need to update the field instance settings,
  • 7:21
    which is what that just did.
  • 7:23
    Now if I click on Configuration and then Account Settings,
  • 7:26
    from the Manage Fields tab for our Drupal user entity type,
  • 7:32
    we can edit the MailChimp subscription field.
  • 7:35
    I'll click Edit here.
  • 7:37
    Then if I scroll down you'll notice that the Locations
  • 7:40
    and Birthday merge fields we just added in MailChimp
  • 7:44
    and then synchronized over to Drupal
  • 7:46
    appear here as options for mapping Drupal field values
  • 7:50
    to MailChimp field values.
  • 7:53
    The user interface for doing this is a Select list.
  • 7:55
    If you open the Select list,
  • 7:57
    what you're seeing are the options here.
  • 8:00
    The things in the select list are all of the user entity properties and fields,
  • 8:05
    so things like the user ID and the user name,
  • 8:07
    which are properties, and then any fields that we've configured,
  • 8:10
    like the first name and last name fields.
  • 8:12
    What I'm doing is saying for the first name merge field in MailChimp
  • 8:17
    when someone creates or edits an entity of this type
  • 8:20
    that has this particular field on it,
  • 8:22
    use the value from whatever I select here
  • 8:25
    to populate the field in MailChimp.
  • 8:26
    I could choose first name and last name.
  • 8:30
    Conveniently they match in our case.
  • 8:32
    I've got two text fields in Drupal
  • 8:35
    that when I update my account will merge their values
  • 8:38
    into the corresponding text fields in MailChimp.
  • 8:41
    Let's save this and confirm that it's working.
  • 8:43
    And we'll come back and deal with the locations and birthday fields in a moment.
  • 8:49
    I can save that and then I can navigate to my account,
  • 8:52
    so I'll click on the Hello Admin link in the toolbar
  • 8:55
    and then click Edit.
  • 8:57
    If I scroll down, I'm already subscribed to the Weekly Newsletter mailing list,
  • 9:01
    and I've got fields here for first name and last name.
  • 9:04
    So if I fill those in, say, Joe Shindelar,
  • 9:08
    last name and save,
  • 9:10
    the changes have been saved.
  • 9:12
    And if I switch over to MailChimp,
  • 9:15
    I'm viewing the subscribers to our weekly newsletter.
  • 9:19
    If I refresh the list now,
  • 9:21
    you can see that the admin account
  • 9:24
    from Drupal is subscribed.
  • 9:26
    And the first and last name are populated
  • 9:28
    with the values I entered into my user account in Drupal.
  • 9:31
    Awesome, so let's deal with these locations and birthday fields.
  • 9:34
    These are a little bit trickier for a couple of reasons,
  • 9:38
    one of which is that on the Drupal side of things
  • 9:41
    our location field is a multi-value term reference field.
  • 9:45
    Now, if it was just a single value term reference,
  • 9:48
    it would be easy to figure out what the name is of the term
  • 9:52
    and just load that string into MailChimp.
  • 9:54
    But in our case, someone might choose multiple locations,
  • 9:56
    so we need to provide MailChimp with a comma separated list
  • 9:59
    of those locations.
  • 10:01
    That means a little bit of additional manipulation on the Drupal side
  • 10:03
    to generate that comma separated list.
  • 10:06
    In addition to that,
  • 10:08
    a birthday field in MailChimp has some specific requirements.
  • 10:11
    If we look at the documentation for the MailChimp API,
  • 10:14
    under the lists subscribe formatter
  • 10:18
    there's some information about merge variables
  • 10:21
    or merge fields, the type of field
  • 10:24
    and the values you can put into it.
  • 10:26
    Let's take a look at some of these.
  • 10:28
    There's the location field,
  • 10:30
    latitude, longitude, etc.
  • 10:32
    There's simple text fields or email
  • 10:34
    like we're dealing with currently, and then there's the birthday field.
  • 10:37
    Let's find that.
  • 10:39
    The birthday field here says this is expected to be passed in
  • 10:44
    in the format month/day.
  • 10:46
    But in Drupal, this is stored as a Unix time stamp.
  • 10:49
    We're going to need to coerce that Unix time stamp
  • 10:52
    into the format that MailChimp is expecting.
  • 10:54
    We're going to demonstrate it with this birthday field,
  • 10:57
    but this same technique should work
  • 10:59
    for any of the other complex MailChimp data types,
  • 11:02
    like drop downs or locations or whatever the case may be.
  • 11:06
    Let's switch back to Drupal.
  • 11:09
    On our Drupal site,
  • 11:11
    I'm going to go back to the interface for editing
  • 11:13
    the MailChimp subscribe field.
  • 11:15
    I'll go to Configuration, Account settings,
  • 11:17
    Manage Fields.
  • 11:19
    I'm going to edit this Subscriptions field.
  • 11:22
    Scroll down.
  • 11:24
    What I want to do is map the Locations and Birthday field.
  • 11:28
    The thing is that using this UI
  • 11:31
    there isn't any way for me to really do any additional manipulation
  • 11:34
    of the values before sending them to MailChimp.
  • 11:36
    However, I can enable advanced mapping.
  • 11:39
    I'm going to click this box.
  • 11:41
    What this has done is it's changed from a select list based input
  • 11:45
    to simple text fields,
  • 11:47
    and the text fields I can enter tokens into
  • 11:49
    using standard Drupal token syntax like so,
  • 11:52
    user:mail or user:field-first-name, etc.
  • 11:58
    It's actually gone ahead and populated those
  • 12:00
    with the existing tokens
  • 12:02
    for the things I had previously chosen.
  • 12:04
    The benefit here is that using tokens
  • 12:08
    we have a lot more control
  • 12:10
    over how the data will eventually be output and replaced.
  • 12:15
    Let's do this.
  • 12:17
    For Locations, I'm going to click this "Browse available tokens" link.
  • 12:20
    This isn't present by default.
  • 12:22
    This happens to be here because I've got the Token Module installed.
  • 12:25
    The Token Module provides this user interface.
  • 12:28
    It pops up a list of all the available tokens,
  • 12:31
    and I can choose from here a token to insert into the Locations field.
  • 12:35
    And when Drupal goes to send this data
  • 12:38
    to MailChimp, what it will do is it will replace
  • 12:40
    the token with the appropriate value.
  • 12:43
    Using tokens I have access to a lot more information
  • 12:46
    than was available before, including things that aren't specific
  • 12:49
    to this entity but are more global to the site,
  • 12:51
    like the current date or information about the site name and so forth.
  • 12:55
    One thing to be aware of, particularly with user entities,
  • 12:59
    is the difference between the Current user token and Users.
  • 13:03
    Current user will always refer to whichever user
  • 13:06
    is currently logged in and using the site.
  • 13:08
    That means if I'm logged in as an administrator
  • 13:11
    and I went to your account and I made some changes and then I clicked Save,
  • 13:14
    and it was using the Current user token,
  • 13:17
    when it tried to merge the values into MailChimp
  • 13:19
    it would actually take the value from my user name
  • 13:23
    and put it into your MailChimp field.
  • 13:25
    That's not exactly what we want,
  • 13:27
    so make sure we're using the Users tokens.
  • 13:29
    Once I expand that,
  • 13:31
    I've got access to all kinds of information,
  • 13:33
    a lot of the things that we saw in the select list,
  • 13:35
    and some additional things as well.
  • 13:37
    Here, I'm going to choose the field locations option,
  • 13:41
    and I'm just going to select that.
  • 13:44
    And then we'll close the overlay here,
  • 13:47
    and it's inserted that token into the Locations text field here.
  • 13:51
    Token Module is really smart about handling multi-value fields.
  • 13:54
    In this case where we've got a multi-value term reference field
  • 13:58
    it will take care of finding the names of all of the terms
  • 14:01
    and joining them together with a comma.
  • 14:04
    If we wanted to, there's more advanced syntax
  • 14:06
    that we could get into with the Token Module to, say,
  • 14:09
    separate these with a tab instead of a comma.
  • 14:11
    But commas will work fine for me.
  • 14:14
    The other thing we need to do then is figure out how to make this birthday field
  • 14:17
    use the month/day format.
  • 14:19
    If I browse available tokens again
  • 14:21
    and I go to Users,
  • 14:23
    I've got the User Birthday field here.
  • 14:25
    I'll expand that, and there's a few options
  • 14:28
    for how I could output this birthday date.
  • 14:31
    I could use any of Drupal's existing date formats.
  • 14:35
    I could put out the raw time stamp, or I could use this Custom format,
  • 14:39
    which allows me to choose a PHP date function string
  • 14:43
    as the customs format here.
  • 14:45
    I'm going to do that.
  • 14:47
    I'm going to say use the Custom format for our birthday field,
  • 14:49
    and I'll insert that and then close the overlay,
  • 14:53
    and you can see here the question mark
  • 14:55
    needs to be replaced with the string
  • 14:58
    from the PHP date function that should be used for the formatting here.
  • 15:01
    So I'm going to do M for month,
  • 15:03
    and then I'm going to do slash,
  • 15:05
    and then I'll do a second one, like so.
  • 15:08
    And use D instead of M,
  • 15:11
    so I'll have month/day.
  • 15:13
    Drupal will replace both of those tokens
  • 15:16
    with the appropriate output,
  • 15:18
    combine it together with the slash in between,
  • 15:20
    and now we've got the format that MailChimp needs.
  • 15:22
  • 15:24
    Let me save the field settings here,
  • 15:26
    and now if I go and edit my user account,
  • 15:28
    so I'll go back to Hello Admin and then click on Edit,
  • 15:31
    I'll scroll down, and I'm going to set values
  • 15:34
    for the month.
  • 15:36
    We'll say my birthday is April 1st in 2012.
  • 15:40
    It looks like we probably should really configure this date field
  • 15:44
    to go back a bit further, but this will work for our demonstration here.
  • 15:48
    I've set a birthday, and I'll choose the two locations
  • 15:51
    where I like to go to get ice cream,
  • 15:53
    Aspen and Carbondale, and click Save.
  • 15:57
    The changes have been saved in Drupal.
  • 15:59
    If I switch over to MailChimp now
  • 16:01
    and I refresh the list,
  • 16:03
    you can see that the locations have been merged into the Locations field,
  • 16:07
    comma separated, and the birthday exists
  • 16:10
    in the appropriate format within MailChimp.
  • 16:12
  • 16:14
    We saw how you can merge both simple text fields
  • 16:16
    and handle some of the more complex formatting
  • 16:18
    for fields like the birthday field in MailChimp using tokens.
  • 16:22
    In this tutorial, we took a look at what merge fields are in MailChimp
  • 16:27
    and added a couple of additional ones to our MailChimp mailing list.
  • 16:31
    Our list already had first name and last name fields,
  • 16:34
    but we added a location field and a birthday field.
  • 16:37
    We also already had those fields in Drupal,
  • 16:41
    so now we've got a scenario where on the MailChimp side
  • 16:44
    and the Drupal side we have corresponding fields,
  • 16:46
    and we need to figure out how to synchronize the data between them.
  • 16:49
    We're able to do that by configuring our MailChimp subscription field
  • 16:53
    to synchronize the content from fields within Drupal
  • 16:56
    to the MailChimp merge fields
  • 16:58
    using either the Select widget,
  • 17:01
    which allowed us to pick any property or entity,
  • 17:03
    or token replacement in order to handle some of the more advanced formatting
  • 17:07
    necessary for different types of MailChimp merge fields.

Collect Additional Information with Merge Fields


MailChimp allows us to collect additional information about contacts that are subscribed to a list. Similar to Drupal's Field UI you can add any number of new data points, called merge fields, to a contact in MailChimp. In this lesson we'll look at how to configure merge fields in the MailChimp UI, and then demonstrate how to synchronize the value of a field in Drupal with the MailChimp merge field. This will allow us to create first and last name fields in Drupal that keep the contacts information up to date in MailChimp.

Then, we'll install the date and Token modules, and add a Birthday field to our Drupal user entities. This will allow us to look at some of the more complex configuration options available when merging field values in MailChimp. By checking the advanced option on the form for configuring the mapping of Drupal field values to MailChimp merge fields we can allow users to use Drupal 7 tokens. This opens up all kinds of new options for massaging the data within Drupal a little before sending it to MailChimp so that we can match the format that MailChimp's API expects the data to be in.

For example, we’ll use tokens to customize the format of a Drupal date field, which stores its value in the database using ISO Date format, so that it matches the MM/DD format that MailChimp expects, using a token like the following: [user:field-birthday-iso:custom:m]/[user:field-birthday-iso:custom:d]

If you're using the advanced field mapping form I highly recommend that you also install the Token module. The MailChimp module provides integration with the Token module’s UI for browsing the list of available tokens, making it much easier to create complex mapping patterns.

By the end of this tutorial you should be able to add additional merge fields to a MailChimp list and keep the content of those fields in sync with fields from a Drupal user account.

Further your learning

  • What is the use case for merge fields?
  • List the three merge fields that are added to every MailChimp list by default? Which of these is required, and why?
  • When you are configuring the mapping between a Drupal field and a MailChimp merge field using the select list interface the list is populated with a variety of options. Where do these options come from, and what do they represent?
  • Further exploration: Can you setup Drupal to collect a users address/location and then merge that data into MailChimp using a MailChimp address merge field?

Series Sponsored by MailChimp

Log in or sign up to download companion files.