Integral MailChimp Developer Guide

The following guide is meant for those familiar with developing in WordPress. It assumes a moderate understanding of hooks, functions and other WordPress concepts.

If you are new to developing in WordPress you may wish to visit the WordPress Codex to familiarize yourself with them.

Custom Merge Tags

Integral MailChimp allows you to seamlessly integrate the custom user data (i.e. Merge Tags) in your WordPress site with your MailChimp lists in order to create list segments that allow you to fine tune which subscribers receive your email campaigns.

The process follows these steps:

  1. During the plugin setup wizard you will navigate to the List Management page and drag-n-drop the available Merge Tags into either Active or Inactive status.
  2. That process allows for other plugins to introduce additional user Merge Tags that you can sync with MailChimp via our registration hook.
  3. Then whenever a user gets added or updated in WordPress it triggers another hook that fetches the data associated with those Merge Tags to send over to MailChimp for building list segments with.

The following guide will show you how to setup those hooks to take advantage of this system.

Registering the Custom Merge Tags

Setting up the initial registration hook

The first step in syncing your user data is to register the Merge Tag itself:

  1. You’ll need to hook into the Integral MailChimp method that collects the Merge Tag info.
  2. The hook ‘integral_mailchimp_plugin_sync_merge_tags’ will handle the first part of this process.
  3. The function name ‘get_sync_merge_tag_definitions’ will refer to your function for providing the definitions as outlined below.
  4. Use one of the methods below as a guide depending on your setup. (NOTE: For those placing this call in functions.php, the first simple example is recommended)
Examples:

Procedural PHP (simple method)

//- INTEGRAL MAILCHIMP MERGE TAG REGISTRATION HOOK 
//- To provide the merge tag definition 
add_filter('integral_mailchimp_plugin_sync_merge_tags', 'get_sync_merge_tag_definitions');

Object Oriented PHP External Call (class method)

//- INTEGRAL MAILCHIMP MERGE TAG REGISTRATION HOOK 
//- To provide the merge tag definition 
add_filter('integral_mailchimp_plugin_sync_merge_tags', array('my_class', 'get_sync_merge_tag_definitions'));

Object Oriented PHP Internal Call (class method)

//- INTEGRAL MAILCHIMP MERGE TAG REGISTRATION HOOK 
//- To provide the merge tag definition 
add_filter('integral_mailchimp_plugin_sync_merge_tags', array(__CLASS__, 'get_sync_merge_tag_definitions'));
Setting up the registration definitions

Next you’ll need to provide the actual definitions:

  1. The index for the array item will be the Tag itself. (i.e. ‘EXAMPLE’ or ‘B_DAY’)
    • This should be UPPERCASE
    • No spaces
    • Underscores OK
    • No more than 10 characters!
  2. Choose the correct data type for your Merge Tag: (learn more here)
    • text
    • number
    • radio (radio buttons)
    • dropdown (dropdown select list)
    • date
    • address
    • phone
    • url
    • imageurl
    • zip
    • birthday (date without the year)
  3. Data types like number, date and birthday allow for doing value based comparisons later on when you’re building your list segments (i.e. BIRTHDAY = Today or NUMBER > some_score_value)
  4. Provide a Tag Name (i.e. ‘Account Status’ or ‘Birthday’)
  5. Set whether the Tag should be required if/when a user chooses to register to the list through the MailChimp interface.
  6. Set whether the Tag should be visible to the public when viewing the MailChimp profile.
  7. Set whether the Tag should be shown when viewing in the MailChimp admin interface.
  8. Provide the name of who/what the Tag should be attributed to. This is only used in the List Managment page to help you distinguish which plugins are providing what tags.
Examples:
function get_sync_merge_tag_definitions($tags) {
    $tags['EXAMPLE'] = array(
        'name' => 'Example Tag',                   //- This is the name that will show up in the MailChimp interface
        'field_type' => 'text',                    //- The field type (read more: https://apidocs.mailchimp.com/api/2.0/lists/merge-var-add.php)
        'req' => FALSE,                            //- Whether this value is required when filling in the subscribe form via the MailChimp site
        'public' => FALSE,                         //- Whether this field is visible to the public
        'show' => TRUE,                            //- Whether this field is visible in the field list in MailChimp
        'plugin_name' => 'Your Plugin/Site Name'   //- Where this Merge Tag is derived from (NOTE: For plugin purposes only to display in the List Management interface)
    );

    $tags['BIRTHDAY'] = array(
        'name' => 'Birthday',
        'field_type' => 'birthday',
        'req' => FALSE,
        'public' => FALSE,
        'show' => TRUE,
        'plugin_name' => 'Your Plugin/Site Name'
    );

    $tags['STATUS'] = array(
        'name' => 'Account Status',
        'field_type' => 'number',
        'req' => FALSE,
        'public' => FALSE,
        'show' => TRUE,
        'default_value' => 1,
        'plugin_name' => 'Your Plugin/Site Name'
    );

    return $tags;

}

Providing the Custom Merge Tag Values

Setting up the values hook

The second step in syncing your user data is to actually calculate and respond with the actual Merge Tag values for a given user:

  1. You’ll need to hook into the Integral MailChimp method that collects the Merge Tag values.
  2. The hook ‘integral_mailchimp_plugin_get_merge_tags’ will handle the second part of this process.
  3. The function name ‘get_sync_merge_tag_values’ will refer to your function for providing the definitions as outlined below.
  4. Use one of the methods below as a guide depending on your setup. (NOTE: For those placing this call in functions.php, the first simple example is recommended)
Examples:

Procedural PHP (simple method)

//- INTEGRAL MAILCHIMP MERGE TAG VALUES HOOK 
//- To provide the merge tag values 
add_filter('integral_mailchimp_plugin_get_merge_tags', 'get_sync_merge_tag_values', 10, 2);

Object Oriented PHP External Call (class method)

//- INTEGRAL MAILCHIMP MERGE TAG VALUES HOOK 
//- To provide the merge tag values 
add_filter('integral_mailchimp_plugin_get_merge_tags', array('my_class', 'get_sync_merge_tag_values'), 10, 2);

Object Oriented PHP Internal Call (class method)

//- INTEGRAL MAILCHIMP MERGE TAG REGISTRATION HOOK 
//- To provide the merge tag values 
add_filter('integral_mailchimp_plugin_get_merge_tags', array(__CLASS__, 'get_sync_merge_tag_values'), 10, 2);
Providing the values

Next you’ll need to provide the actual values for each Merge Tag:

  1. Using the $user object passed in, you’ll need to fetch and/or calculate the necessary values to respond with.
  2. If another plugin is implementing custom data that you want to use, you’ll need to find out how to fetch that data to respond with.
  3. Once the values have been fetched and/or calculated, load them into their corresponding tag item in the $tags array and return the array.
Examples:
function get_sync_merge_tag_values($tags, $user) {
    //- Load the provided user's meta using the user ID
    $user_meta = get_user_meta($user->ID);
    
    //- Process the data and return the values as necessary
    $tags['EXAMPLE'] = 'Some example text';
    
    $tags['BIRTHDAY'] = $user_meta->user_birthday;

    $tags['STATUS'] = $user_meta->account_status;

    return $tags;

}

Trigger User Actions

Manually triggering the user profile processes

You may occasionally find the need to trigger a user creation, update, or delete process if you have a plugin that creates, makes modifications to, or deletes the user profile outside of the built in WordPress functions.

  1. For user creations use the ‘integral_mailchimp_user_create’.
  2. For user updates use the ‘integral_mailchimp_user_update’.
  3. For user deletes use the ‘integral_mailchimp_user_delete’.
Examples:

User Create

//- INTEGRAL MAILCHIMP USER CREATE 
//- Trigger the plugin user create process 
do_action('integral_mailchimp_user_create', $user_id);

User Update

//- INTEGRAL MAILCHIMP USER UPDATE 
//- Trigger the plugin user update process 
do_action('integral_mailchimp_user_update', $user_id, $old_user_data);

User Delete

//- INTEGRAL MAILCHIMP USER DELETE 
//- Trigger the plugin user delete process 
do_action('integral_mailchimp_user_delete', $user_id);

Show Email Archives

Although Integral MailChimp uses a custom post type to store your email campaigns, displaying an archive of them on your site isn’t quite as simple as adding a standard archives page or using your favorite theme or plugin to display a list of them. Why? In order to recreate the MailChimp template editing experience we pull in the full email HTML and store it in the database. By full HTML we mean a complete HTML document, full of all the inline styles that MailChimp generates in order to make sure your email displays consistently across various browsers and email programs.

If you simply output the post content to your site, the MailChimp styles would (potentially) conflict with your theme styles and vice versa. And when we say “potentially” we mean “will” — it’s just a question of how much.

In an upcoming release we’ll be adding a shortcode builder that will allow you to easily display email archives on any page of your site. In the meantime, you can do it with a bit of code and a custom template. If you’re not familiar with how to add custom templates to your theme, check out the WordPress Codex tutorial here. If you are, grab the code from our Gist page and use it in your own theme. Want to see it in action? Visit: http://demo.integralwp.com/email-archives/

Disable Automatic Sync’ing

One of our customers contacted us saying that they were using another tool to manage their MailChimp user list and only wanted to use ours for creating and sending emails. How, they wondered, could they disable the automatic default list sync’ing?

If you find yourself with the same need, simply adding the following code to your theme’s functions.php file will disable all automatic sync’ing. WARNING: If you are not sync’ing your WordPress user data and MailChimp list data via some other means disabling the automatic sycn’ing will lead to issues. For example, if a user updates their email address via your website it won’t be updated in MailChimp and they will no longer receive your emails (or they’ll still get them to an old address and get annoyed!).

With that warning in mind, here is the code:

 //- disable IMC MailChimp Automatic List Sync'ing
$priority = 888;
remove_action('user_register', array('IMC\Controllers\User_Lists_Controller', 'add_user_to_default_list'), $priority);
remove_action('delete_user', array('IMC\Controllers\User_Lists_Controller', 'remove_user_from_all_lists'), $priority);
remove_action('profile_update', array('IMC\Controllers\User_Lists_Controller', 'update_user_in_all_lists'), $priority);
            
if (is_multisite()) {
	remove_action('add_user_to_blog', array('IMC\Controllers\User_Lists_Controller', 'add_blog_user_to_default_list'), $priority);
	remove_action('remove_user_from_blog', array('IMC\Controllers\User_Lists_Controller', 'remove_blog_user_from_all_lists'), $priority);
}