Product Support

MailChimp Integration

Integrates Participants Database with your MailChimp account.

Product Setup

This plugin requires you have an account established with MailChimp before you configure it. Once you have your MailChimp account set up, you’ll need to get an API Key.

Getting Your MailChimp API Key

On your avatar menu (upper right corner while logged in to MailChimp) click on “account.” Once there, under the “extras” menu, select “API Keys.” On that screen, you’re given a way to create an API key. You can have several keys, so even if you have a key, it’s a good idea to create a new one for this purpose. Give it a name so you know where it is being used. Once the key code is generated, copy and paste it into the “API Key” setting in the MailChimp Integration settings menu, found under Participants Database in the WP admin.

Setting Up Your Mailing List

When you click on “Save Changes” the API Key will be used to get your list of mailing lists at MailChimp. You will need to have at least one mailing list established in order to use the plugin because new subscribers have to go to a specific list. In the “Subscription List” dropdown will be your mailing lists at MailChimp. If you don’t see it, click on “Save Changes” to refresh the list.

Select the list you want your Participants Database signups to be subscribed to.

Set Up Your “Opt-In” Checkbox

In most cases, you’ll want to provide a way for your users to opt-in to your mailing list. Do this by creating an opt-in field that consists of a check box with the values “yes,no” You can default it to “yes” if you want it checked to begin with. Once that is set up, you need to tell the plugin which field it is in the List Select Field setting.

If you want to use another language or give the checkbox a different label, you can use the value label format like this: Yes::yes,No::no

As long as the saved values (the second of each :: pair) are “yes” and “no” it will work.

Completing the Setup

Once you have the API Key and mailing list set up, you can make sure the rest of the settings are what you want. Take a look at the “Settings” tab here for more explanation.

Importing Subscribers

When you import records using a CSV file, these will also be synchronized with your MailChimp list. You can use a CSV import to add a bunch of subscribers or update their subscription status over at MailChimp.

If you already have records in your Participants Database and you want to add them all to your MailChimp list, you need to export them, then re-import them (using the record ID as a match field so you won’t end up with duplicates) which will update all of them with your MailChimp list. Be sure the needed fields are configured to be included in the CSV export by having the “CSV” box checked in the field definition.

Note: CSV imports must contain both the “email” and “list select field” data in order for the subscriber to be added or updated at MailChimp.

Two-Way Synchronization

the webhook link…yours will look different.

When a subscriber receives an email you’ve sent using MailChimp, there is an unsubscribe link they can use to be unsubscribed. In order for this to be reflected in your Participants Database record, a communication link between MailChimp and your WordPress site must be established. This is done using a “webhook” which is a secure URL that the MailChimp list can use to communicate to your WP site.

To set up a webhook, first findĀ the webhook URL that you will see at the top of the MailChimp Integration settings page in your WP admin. Ā Copy that URL. We’re going to use that over at MailChimp, but first you must flush the permalinks to activate the webhook URL. To do this, go to the “permalinks” setting under the Settings item in your WP admin. On the permalinks settings page just click on “Save Changes” and that will flush the permalinks and make sure the webhook URL is set up to receive data from MailChimp.

Now, go to MailChimp and select the list you are using with Participants Database. Go to the settings page for that list and find the “webhooks” setting.

On the webhooks page, click on the “Create New Webhook” button found on the upper right. This will open a form where you can paste the webhook URL you got from the plugin settings. Once that is saved, you will be able to select what type of messages will be sent. Just accept the defaults and save the webhook.

If you get some kind of error message when trying to set up the webhook, make sure you copied in the exact URL given in the plugin settings. Also, flush the permalinks to be sure WP has the URL set up. Errors such as a 500 or 403 indicate possible security rules on your web server designed to block unauthorized access. Talk to your web host about the problem in cases like this. MailChimp also has a support page for webhooks that could be helpful.

Manually Updating Multiple Records

As of version 1.5, it is possible to update multiple records in a single operation. This is done on the “List Participants” page in the Participants Database admin, there are new MailChimp functions in the “With Selected” dropdown.

To update (synchronize with MailChimp) multiple records, selected the records you want updated, then select “Update to MailChimp” and click “Apply.” All your merge fields and subscribe statuses will be updated to MailChimp, so all the subscriber’s info there will match the info in Participants Database.

Mass Subscribe/Unsubscribe

If you need to subscribe or unsubscribe multiple records, you can to that in a similar way.

Product Settings

API Key

This is the key code provided by MailChimp that is unique to your MailChimp account.

Subscription List

Once you have entered your API key and saved the settings, you can select which list people will be signed up to when they register.

List Select Field

This is the name of the field used to opt in to your list. Usually, it’s a checkbox whereĀ they simply say “yes” to being added to the list.

Use Double Opt-In

This means that when someone signs up and indicates they want to join the list, MailChimp sends them an email where they can confirm that choice. This is a really good idea to avoid trouble such as people getting your newsletter who actually don’t want it, or getting spam email addresses into your list. Please note that in some countries, a double-opt-in is a legal requirement for mass email.

The way this works is new registrations will have a “pending” status when they sign up. When (or if) they confirm the subscription, their status will be changed to “subscribed.”

Note: when using double opt-in, new registrations will not be visible in MailChimp until they confirm their subscription. Before they confirm, they are considered “pending” and will not show up in your lists at MailChimp. You can find those registrations at MailChimp if you search for the email address.

Pending Label

While a registrant has a pending status, this label is used for the value of the List Select Field. You can use this in list searches to find people who have not confirmed their subscription yet.

Merge Fields

This setting uses a special string to define additional fields that will be saved in the MailChimp list. Typically, this is their first and last name, but it can be just about anything. It does have to be a field that is included in the Participants Database form because otherwise there won’t be any value to save to the MailChimp subscriber list. The default value for the setting is:

first_name:FNAME,last_name:LNAME

The way this works is thisĀ is actually a map of the Participants Database field to the MailChimp field. The format is pdb_field:MAILCHIMP_FIELD with each field pair separated by commas. This is a simple one-to-one mapping: for instance it’s not possible to combine several Participants Database fields into a single MailChimp field.

The Mismatched Merge Fields Warning

If the list of merge fields you have defined in this setting don’t match the list of merge fields defined at MailChimp, you will get a warning message. You can ignore this if you want, the main functionality will work as expected, and any merge fields that do match will work.

What it means is that, for instance, if you didn’t have a “city” merge field defined here, and you did at MailChimp, the data for the registrant’s city will not be sent to MailChimp. The warning is so you will know why your merge fields are not getting populated with data.

F.A.Q.

If a user unsubscribes on their profile page, will they be unsubscribed at MailChimp?

Yes, every time a record is updated on your site, that info is passed to MailChimp, so they can unsubscribe in either place, it won’t matter, they stay synchronized.

I'm not getting subscriber updates from MailChimp, how do I get webhooks working?

To troubleshoot webhooks, follow these steps:

  1. Check the “Subscription List” setting in the add-0n settings and make sure you have the correct list selected
  2. Check the webhook URL at the top of the page. Now go to MailChimp and check the webhook for the list (found in the list’s settings page) Make sure they are the same.
  3. Copy the webhook URL and try it in a browser. You should get a “No request details found.” message. If you get a 403, or a 500, check your site security filters or contact your web host with the information.
  4. If you get a 404, refresh the permalinks in the general settings of your WordPress site, then try to open the webhook URL in the browser again.
I have Double Opt-In checked, and I'm getting signups, but they aren't appearing at MailChimp, what's happening?

Having Double Opt-In checked changes how things work in several ways.

If you have “Use Double Opt-In” checked, andĀ someone signs up, their info is sent to MailChimp only if they have the “List Select Field” checked. In both cases, you won’t see them at MailChimp at first.

If they agree to be on the list when they sing up, their info will be sent to MailChimp, but you will not see them in the list thereĀ until they confirm the opt-in by email. You can still find them with a search, however. You’ll see their status is “pending.”

If they don’t agree to join the list, their info won’t be sent to MailChimp at all. In this case, if they later update their record to join the list, their info will be sent to MailChimp at that time and they will need to confirm in order to join the list.

Support Discussions for MailChimp Integration

  • I have some PDB records with blank emails. When an admin enters an email, the appropriate new record is generated in MailChimp. The new record however is created as ā€œUnsubscribedā€; requiring someone go into MailChimp to manually Subscribe the new MailChimp user.

    Iā€™m assuming this is due to the List Select field being unchecked; when I originally exported and imported back the records in PDB to generate the initial MailChimp list, the List Select field was checked, and all the records with email were all added as Subscribed. Somehow though, the List Select field is now clear on all of the PDB records, so any new adds show up as Unsubscribed.

    Does List Select value get cleared after an initial subscription, whether or not the record has a valid email? Mahalo, as always!

    • You are correct in that when a new subscriber is added to MailChimp, the list select field value is used to determine whether to add the person as subscribed or not.

      You’re reporting that all of the list select field values have been cleared in your records, that would not happen unless you took a specific action to do that. The one exception to that is if the field type (Form Element) is changed in the field definition. If the field is changed to a type that is incompatible with the data that is already present, data loss can occur. There is a warning and a confirmation dialog to let you know this could happen when you change the form element of a field that has stored data. This would not affect MailChimp subscribers as you have seen.

      If you want new entries to be subscribed by default, you can set the default value of your list select field to whatever the “subscribed” value is for your field.

      • OK, I exported all the records, changed the List Select field for all of them to “Yes”, and then imported them again. I then went to a record without an email, added an email, and saved the record. The result; the List Select field was set to “No”, and the record was added to MailChimp as “Unsubscribed”.

        The only thing I’m not doing is that I have not enabled the two way synchronization; data flows from PDB to MailChimp, but not in reverse.

        Mahalo!

        • P.S. I do not list the List Select field in the list of fields to be merged in MailChimp, and I double checked and the only record with the List Select field set to “No” is the one that I added the email to.

        • I found the problem. I apparently used the wrong type of database field for the selection; I chose Checkbox with a “Yes” and “No” field. When I changed the database field to Radio Button, everything worked correctly.

        • thanks for the clarification… I wondered if that was possibly the issue.

          The list select field does not need to be part of the merge fields, all it does is set the subscription status of the subscriber in MailChimp, no need for that value to be part of the subscriber’s data at MailChimp.

  • I am receiving this message:

    The merge fields defined in the settings here do not match the merge fields defined for this list at MailChimp, which can result in lost data.

    The merge fields setting is missing the ADDRESS field.

    • This is telling you that the Merge Fields Configuration setting is missing the ADDRESS field. You must either add an address from fron the Participants Database fields, or remove the merge field from MailChimp if you don’t need to use it.
      Check the “Merge Fields” section in the Mail Chimp setup instructions.

  • I am following your instructions and got to the List Select Field and there is nothing listed in the dropdown.

    In our database if the person is “active” then they have subscribed to receive emails. It’s a text line field that will have a “T” in it for true.

    • If you are adapting an existing database to use the List Select Field, you will need to configure it to use the existing data. For example, you have a “T” in the data for a subscribed person. In that case, you can use an options configuration string like this:

      Active::T,Inactive::F

      If the option configuration does not match the existing data, it will show a blank because it does not recognize the value.

  • If I clear the Email field in the PDB record, it does not change the corresponding MailChimp record.

    We have records for each resource in our organization; when a resource is sold to a new owner, we often clear the name and email address of the old owner until the new person’s information is available.

    Would it make sense for a record that has had its email address removed to mark the corresponding MailChimp address as Unsubscribed? This would solve our issue.

    • The way this tool works, you would need instead to unsubscribe the account, then update the email address when you have the new one. Since MailChimp subscribers are identified by email address, it doesn’t work to set a blank email address at MailChimp.

  • When someone unsubscribes from MailChimp I see that the List Select Field is change from yes to no, however I have another database field that contains email list choices that ultimately are translated into segments in mailchimp for different mailing lists. So….when someone unsubscribes I end up with the Email Subscription (List Select Field) set to no, which is good, but the email list choices are still present. I would like to blank-out that list when someone unsubscribes. I have tried exporting a csv list where the email subscription flag is set to No and email list choices are present….but when I blank out the email list choices and try to upload/update matching records using the private ID the update is ignored because the field I am trying to update is blank! Long story short, how do you update a field in the database using the upload csv function when what you want to update the field to…is blanks or null? Any suggestions would be appreciated.

    • It is true that a blank field in a CSV import will be ignored. This is to avoid accidental data loss. You could add a “None” option to the list selector to indicate that no lists are subscribed to.

  • Thank you for this amazing database and extensions, it is a lifesaver for not-for-profit organizing groups. I saw the lament about inexpensive tech support and wanted to suggest WPFixIt.com. They keep things affordable by breaking tasks down. If someone needs custom coding they can buy a block of 5 hours for $250. Okay, the coding isn’t perfect, but it is way better than any other service I’ve tried. Thanks again!

Got a Support Question?

You have to agree to the comment policy.

Would you like to be notified of followup comments via e-mail? You can also subscribe without commenting.