← Documentation

Mailchimp

Mailchimp is a powerful marketing platform that helps businesses create and manage email campaigns, store customer information, and access advanced features. The Mailchimp addon allows seamless integration of WordPress contact and subscription forms with Mailchimp mailing lists.

The addon

Mailchimp’s Marketing API is a REST-like HTTP API. Using the API you can manage your account, automations, campaigns, lists, and more. All API requests are validated against an API key using the Basic authentication schema.

To talk with this API, the addon works with an extension of the generic REST bridge class that requires a Basic credential.

A Mailchimp bridge will synchronize your form submissions with your Mailchimp’s account. The addon comes with a couple of templates and workflow jobs to bridge forms to your mailing lists, but you’re not tied to this options: either via templates or via manual set up, you can configure your bridges to target any API endpoint.

How to use

The first step to use the addon is to activate it on the addons table on the general settings tab.

Once activated, a new tab will be visible on the settings page. If it’s your first time, it should looks like this:

The template wizard

The recommended way to set up a new bridge is to use a template as a starter point. The addon’s template wizard will set up a new Basic credential, a backend connection and a form, all of them linked on a new bridge.

With this setup ready, you can edit the bridge’s form to fit your requirements or manually add new forms and bridge them with the backend / credential you’ve configured on the previous step.

The template wizard will lead you through four steps:

1. Credential

On this step, Forms Bridge will register a new Basic credential based on an API key.

To generate this API key go to your Account settings on your Mailchimp dashboard. Under the Extras > API keys tab, click on Create A Key to generate it. The key requires a name, for example “Forms Bridge”.

Back on WordPress, you have to fulfill the credential step form with a unique name to identify the credential and the value of your key.

2. Backend

The backend step will require you to set a unique name to identify the new connection and to select the API URL that matches your account data center.

There are a few ways to find your data center. It’s the first part of the URL you see in the API keys section of your account; if the URL is https://us6.mailchimp.com/account/api/, then the data center subdomain is us6. It’s also appended to your API key in the form key-dc; if your API key is 0123456789abcdef0123456789abcde-us6, then the data center subdomain is us6.

2. Form

In this step you have to choose the title of the form the template are going to create. If there is a compatible form, the wizard allows you to reuse the existing form and skip the form creation.

3. Bridge

On the last step of the wizard, you have to set a unique name for the new bridge. In addition to the name, and depending on the template you are using, this step will require more or less fields to be informed. The required fields will be marked with a red asterisk

After that, click on submit and Forms Bridge will generate the credential, backend, form and bridge setting. It only remains to publish the new form on a public page and wait for a new form submission!

Manual set up

With templates, you can save a lot of time while configuring your bridges, but you can achieve the same result with a manual set up.

A Mailchimp bridge will require the following components:

1. Credential

To configure the Marketing API as a backend to be used on your form bridges you will need to generate an API key going to your Account settings. Under the Extras > API keys tab, click on Create A Key and create a new key. The key requires a name, for example “Forms Bridge”. The key value should looks like a long random string like 95UkqT5NG74w8dz9171J7xe7WL3002mb8-us1.

With your API key on the clipboard, go to Settings > Forms Bridge > HTTP > Authentication on your WordPress admin page and register a new authentication credential.

Select Basic as the authentication schema and set forms-bridge as the Client ID and your API key as the Client secret. In addition, you have to choose a unique name to identify this new credential.

2. Backend

To configure the Marketing API as a backend follow this steps:

1. Add a new backend with a unique name (Mailchimp API, for example)
2. Set the backend URL to https://{dc}.api.mailchimp.com replacing the dc param with your account data center prefix.
3. Select JSON as the Encoding Schema
4. Add Accept as an HTTP header with application/json as value
5. Select the Basic credential you’ve configured on the previous step.

3. Form

Get your preferred form builder and create a new form. Once created, you can choose it as the target form to be bridged on the bridges panel of the addon. If your form fields does not match the desired API module’s layout, you can use bridge’s field mappers to rename them.

4. Bridge

The addon’s bridge is an extension of the generic REST bridge. Because of this they looks so similar. Like the REST bridge, the addon’s bridge requires a unique name, a backend, a form, an endpoint and an HTTP method.

The bridge endpoint has to exists on the Marketing API. To get a comprehensive list of the available endpoints you can check the official documentation. For example, to get your subscription form bridged you have to set the bridge endpoint to /3.0/lists/{list_id}/members.

Troubleshooting

To troubleshooting your bridges you can use the plugin’s debug console from the General Settings page. Enable the debug mode and submit a sample form response to see what’s going on under the hood. Take a look to our tutorial about how to use the debug console.

Common issues

1. Authentication failures
   • Check data center parameter of your backend URL
   • Verify endpoint and list ID
2. Missing data
   • Validate field mappings
   • Validate your contact’s custom fields

Templates

The addon comes packed with the following templates:

• Subscription 🔎
  Subscription form template. The resulting bridge will convert form submissions into new list subscriptions.

• Subscription 🔎
  Subscription form template. The resulting bridge will subscribe woocommerce customers to a given mailchimp audience.

Workflow jobs

The addon comes packed with the following workflow jobs:

• Audience subscription 🔎
  Subscribe a new user to an audience

• Skip subscription 🔎
  Skip subscription if the mailchimp field is not true

• Format date fields 🔎
  Gets date, hour and minute fields and merge its values into a date with format Y-m-d H:M:S

• ISO2 country code 🔎
  Gets the ISO2 country code from country names and replace its value

• ISO3 country code 🔎
  Gets the ISO3 country code from country names and replace its value

• Skip submission 🔎
  Skip submission if condition is not truthy

Supported form builders