Connect Mailchimp
You create an API key inside Mailchimp and paste it into MarqIQ. MarqIQ then syncs the members of every audience in the account, and can create the UTM merge fields on the one audience you pick. If you want to know what you are granting before you start, read How connecting a tool works.
Before you start
Permissions required
You need someone who can sign in to the Mailchimp account whose audiences you want and create an API key there. MarqIQ reads the account name, the account email and the total subscriber count back from the key and shows them on the connection, so you can check you connected the account you meant.
Plan required
Connecting works from Starter up. The Create and Create N missing buttons that make merge fields in Mailchimp need an active paid subscription. Without one, Create N missing reads Paid feature · Upgrade, and each field’s Create button carries a padlock and opens the pricing page instead of creating anything. The Tool Operations hub, which holds field mapping, needs Pro or above — the merge-field list on the Mailchimp page itself does not.
- A Mailchimp API key, ending in your data centre — the part after the last hyphen, like `-us1`. MarqIQ reads the data centre out of the key and talks to that data centre only.
- The name of the audience you want the UTM merge fields created on. MarqIQ syncs every audience, but merge fields are managed on one audience at a time.
The key does not expire
A Mailchimp API key has no expiry and nothing renews on a schedule. You reconnect only when you delete the key in Mailchimp or paste a new one.
Get your Mailchimp API key
In Mailchimp, go to Account → Extras → API keys.
Mailchimp explains the screen and what a key is at mailchimp.com/help/about-api-keys
Click Create A Key.
Copy the whole key, including the part after the last hyphen.
That last part is your data centre, and it looks like `us1`, `us21` or `eu1`. MarqIQ builds the address it calls from it, so a key pasted without it is refused before anything is saved.
Mailchimp shows the key once. Copy it now rather than going back for it.
Connect it in MarqIQ
Open Connected Tools in the sidebar.
The page is headed Integrations, and Mailchimp sits under the Marketing Automation heading.
Click the Mailchimp card.
Paste the key into API Key.
The field shows the shape it wants: `{key}-{server}`, for example `abc123-us1`.
Click Connect Mailchimp.
MarqIQ checks the key against Mailchimp straight away rather than saving it and failing later. It reads your account name, account email and total subscriber count back, and names the connection Mailchimp — <your account name>.
If Mailchimp is already connected the button reads Update API key instead. Use it to replace a key without losing your field mappings.
Leave the tab open while the first sync runs.
Connecting starts the sync on its own. The chunk loop runs in your browser, so the status line says "keep this tab open". Close the tab and the run stops where it is. The next sync, manual or scheduled, carries on from the saved point.
Read the result line.
A first load finishes with "Fully synced — N records". Later runs say "Up to date — N changes since your last sync". N counts audience memberships, not people: see the note below.
Note
The very first sync in a new workspace can answer "This workspace’s database was just created, so nothing was synced in this run." Click Sync now again, or leave it — a scheduled run starts within the hour.
Choose the audience for merge fields
Connecting fills the Select Audience card with the audiences in the account, each with its subscriber count. It reads the first 100 audiences Mailchimp returns. MarqIQ picks the first one and marks it Active.
The card is filled by the connect, not by the page
Reload the Mailchimp page and Select Audience is not shown, because the audience list is not read again on load. To change the audience later, paste your key into API Key and click Update API key. The card comes back with the list, and your merge-field mappings are kept.
Click the audience you want in Select Audience.
The chip on it reads Saving… and then Active. MarqIQ reads that audience’s merge fields again as soon as the change is saved.
The picker governs merge fields, not the sync
The audience you select is the one UTM Merge Field Validation reads and writes. The record sync is not limited by it: MarqIQ walks the members of every audience in the account, every time.
What comes across
- Every audience’s members, as contacts. One row per audience membership — the same address in two audiences is two members in Mailchimp too, so it is two rows here.
- The audience name on every row, so a report can split by audience.
- Every merge field on the member, flattened under its own tag. FNAME and LNAME become the first and last name; COMPANY or ORG becomes the company; JOBTITLE or TITLE becomes the job title.
- The member status — subscribed, unsubscribed, cleaned, pending, transactional or archived — as the lifecycle stage.
- The signup source, as the lead status.
- Tags, joined into one value.
- Interest groups that are switched on, and marketing permissions the member has agreed to.
- The per-member statistics Mailchimp reports, such as the average open and click rates.
- Country code and timezone from the member’s location, the language, the VIP flag, the member rating, the email type, the unsubscribe reason and the last note.
- Signup and opt-in timestamps, and the last-changed timestamp, which is what drives incremental syncs.
MarqIQ walks each audience in order of last change, oldest first, 1,000 members at a time, and resumes from where it stopped if a run runs out of time. It reads up to 1,000 audiences from the account. An incremental run asks Mailchimp only for members changed since the last run.
What is left behind on purpose
MarqIQ does not store the member’s signup or opt-in IP address, the email client, the SMS phone number or SMS subscription status, the one-to-one messaging consent, or Mailchimp’s internal ids for the same person.
Deleted members
A member you archive in Mailchimp is marked as deleted here on the next sync, because Mailchimp reports archived members explicitly. A member deleted permanently leaves no trace in the Mailchimp API, so that row stays in MarqIQ until a full resync. The sync says so in its own notes rather than leaving you to find out.
Create the UTM merge fields
The UTM Merge Field Validation section on the Mailchimp page checks the selected audience for the seventeen fields MarqIQ tracks — nine under Most Recent UTM Fields and eight under First Touch UTM Fields — and shows a count for each group, such as "7/9 merge fields found in Mailchimp". It reads the first 100 merge fields on that audience.
Click Create on a field that says Not found in Mailchimp.
MarqIQ creates a text merge field on the selected audience, with the tag in the table below and the MarqIQ field label as its name.
Click Create N missing to make a whole group at once.
The button names the number, as in Create 4 missing. It works through the missing fields in that group one at a time and reloads the list at the end.
Click Map existing instead when you already have a merge field for this.
Type the Mailchimp merge tag, such as `UTM_SRC`, and click Save. Mapping records the tag; it creates nothing in Mailchimp.
A field counts as found when its tag matches the tag below, or when its name matches the MarqIQ label. Both comparisons ignore case.
| MarqIQ field | Mailchimp merge tag |
|---|---|
| UTM Source (Most Recent) | UTMSRC |
| UTM Medium (Most Recent) | UTMMED |
| UTM Campaign (Most Recent) | UTMCAMP |
| UTM Content (Most Recent) | UTMCONT |
| UTM Term (Most Recent) | UTMTERM |
| UTM Campaign ID | UTMCAMPID |
| Entry URL (Most Recent) | ENTRYURL |
| Current URL (Most Recent) | CURURL |
| Referral URL (Most Recent) | REFURL |
| UTM Source (First Touch) | UTMSRC_FT |
| UTM Medium (First Touch) | UTMMED_FT |
| UTM Campaign (First Touch) | UTMCAMP_FT |
| UTM Content (First Touch) | UTMCONT_FT |
| UTM Term (First Touch) | UTMTERM_FT |
| Entry URL (First Touch) | ENTRYURLFT |
| Current URL (First Touch) | CURURL_FT |
| Referral URL (First Touch) | REFURL_FT |
The tags MarqIQ creates and looks for. A Mailchimp merge tag is at most ten characters, which is why first touch is marked with _FT rather than spelled out.
What MarqIQ writes back to Mailchimp
- Merge fields on the selected audience, and only when you click Create or Create N missing. Each one is created as a text field.
- Nothing else. MarqIQ does not add, edit, archive or delete a member, does not change a tag or an interest group, and does not touch your audience settings.
- No campaign is created, sent or scheduled, and no automation is switched on or off.
- The audience you choose in Select Audience is the only audience MarqIQ ever writes to.
What connecting Mailchimp unlocks
- Source truth and Audience health run on the synced members as soon as the first sync finishes.
- Email reads your campaign reports — sends, unique opens, unique clicks, hard and soft bounces and unsubscribes — for the period you ask for.
- Automations reads your Mailchimp automations, which are active, and how many emails each has sent in its lifetime.
- Integration Audit Report covers email campaigns, landing pages and automations for Mailchimp.
- Field Mapping from the Tool Operations hub, on Pro and above, as well as the merge-field list on the Mailchimp page itself.
MarqIQ’s automations reader for Mailchimp follows Mailchimp’s documented API and is tested on payloads of that shape. It has not yet been run against a customer account, unlike the HubSpot and Marketo readers.
What connecting Mailchimp does not unlock
- Field discipline. Mailchimp does not expose a record’s change history, so there is nothing to hold a field to. MarqIQ says that on the card rather than showing an empty analysis.
- Forecast accuracy. Mailchimp has no deals or opportunities, so there is nothing to forecast, and MarqIQ has no forecast reader for it.
- Form fills from Mailchimp’s own signup forms. Mailchimp reports a signup only as a new audience member, which is counted in the synced records. Install the MarqIQ tracking script and the fills it captures on your website appear in that analysis instead.
- Lead scoring and Funnel. MarqIQ has not verified how scoring or a stage ladder works in Mailchimp, so it does not guess. Both run if your members carry a score field or a stage ladder, and otherwise say so without blaming your setup.
- Web-visit figures. Mailchimp does not report them, and landing-page views are not in its API either — the audit shows each page’s status and count instead.
- Hidden tracking fields on your forms, and a source-tracking workflow built for you. Those are HubSpot and Marketo only.
If it did not work
"The API key should end with your data centre, like -us1. Copy the full key from Mailchimp → Account → Extras → API keys."
Why: The part after the last hyphen in what you pasted is not a data centre. MarqIQ turns that part into the address it calls, so it accepts only the `us1` shape — two letters and up to three digits.
Fix: Copy the key again from Mailchimp, from the first character to the last, and paste the whole thing into API Key. A key copied without its suffix, or with a trailing space or a line break, fails this check.
"Could not connect to Mailchimp. Invalid API key. Make sure you copied the full key including the server suffix (e.g. -us1)."
Why: Mailchimp answered 401. The key has been deleted or disabled in Mailchimp, or part of it is missing.
Fix: In Mailchimp, go to Account → Extras → API keys, check the key is still listed and enabled, or click Create A Key for a new one. Paste it into API Key and click Update API key.
"Could not connect to Mailchimp." followed by "Mailchimp returned" and a number
Why: Mailchimp refused the check for a reason other than a bad key — most often it is rate-limiting the account or having trouble at that data centre.
Fix: Wait a few minutes and click Connect Mailchimp again. Nothing was saved, so there is nothing to undo first.
"API Key is required"
Why: The API Key field was empty, or held only spaces, when you clicked Connect Mailchimp.
Fix: Paste the key and click Connect Mailchimp again.
A message naming the tools you have already connected, ending "Disconnect one, or move up a plan."
Why: The plan’s tool allowance is checked before the key is. Starter includes one tool besides Google Tag Manager, so a workspace with a CRM already connected is refused here. The message names your plan, how many tools it includes, and which ones are using the slots.
Fix: Disconnect the tool the message names, or move up a plan. Reconnecting a tool that is already connected is always allowed, so rotating a key is never blocked by the allowance.
A message ending "Business and above allow more than one from the same category."
Why: Mailchimp counts as marketing automation, and Starter, Pro and the trial allow one tool from any one category. The message names the marketing-automation tool that already holds it.
Fix: Disconnect the tool the message names, or move to Business or above.
"This workspace is read-only. Renew the subscription to connect tools."
Why: The subscription has expired. An expired workspace can read what it has and connect nothing new.
Fix: Renew from Plan & billing, then connect Mailchimp again.
The merge-field list is empty, and clicking Create answers "No audience selected"
Why: Merge fields belong to one audience, and none is marked Active yet. It happens when the account had no audiences at the moment you connected.
Fix: Create an audience in Mailchimp if there is none. Paste your key into API Key and click Update API key so the audience list is read again, then pick the audience in Select Audience.
"Mailchimp not connected"
Why: The merge-field list asked for a connection that is no longer there. Mailchimp was disconnected in another tab, or by somebody else in your workspace.
Fix: Paste your key into API Key and click Connect Mailchimp.
"Mailchimp connection is invalid — reconnect the integration."
Why: The stored data centre is no longer a value MarqIQ will turn into an address. The connection is refused rather than a request being sent anywhere unexpected.
Fix: Paste the full key into API Key and click Update API key.
"Creating fields in Mailchimp is a paid feature — upgrade to create them, or map an existing field."
Why: The workspace has no active paid subscription, and a free trial does not count as one. Creating merge fields inside your own tool is a paid feature, and the check runs on the request, not only on the button.
Fix: Upgrade from Plan & billing, or create the merge field in Mailchimp yourself and click Map existing to point MarqIQ at its tag.
"customFieldName required"
Why: You clicked Save under Map existing with the merge-tag box empty.
Fix: Type the Mailchimp merge tag, such as `UTM_SRC`, and click Save.
Creating a merge field fails with a message from Mailchimp, or "Failed to create merge field"
Why: Mailchimp refused the new field and MarqIQ shows Mailchimp’s own reason. The usual one is that a merge field with that tag already exists on the audience.
Fix: Click Refresh above the field list. A field that already exists is matched by its tag and stops being listed as missing. If it exists under a different tag, click Map existing and give MarqIQ that tag.
"Failed to fetch Mailchimp merge fields"
Why: Mailchimp refused the merge-field read for the selected audience. That audience has usually been deleted in Mailchimp since it was chosen.
Fix: Pick a live audience in Select Audience, then click Refresh above the field list.
The sync stops with "Mailchimp rejected the API key — reconnect the integration."
Why: Mailchimp answered 401 or 403 mid-sync. The key was deleted or disabled in Mailchimp after you connected.
Fix: Create a new key in Mailchimp, paste it into API Key, and click Update API key. The sync resumes from where it stopped.
The sync says "This Mailchimp account has no audiences yet."
Why: The account the key belongs to holds no audiences, so there are no members to walk. It is usually the wrong account rather than an empty one.
Fix: Check the account name and account email shown on the connection against the Mailchimp account you meant. Connect a key from the right account if they do not match.
"Another sync is already running for this workspace — it will finish on its own."
Why: The scheduled run holds this workspace. Only one sync per tool runs at a time, by design.
Fix: Nothing. Your data is being refreshed right now. The message is shown in green rather than red for that reason.
The record count in MarqIQ is higher than the subscriber count Mailchimp shows
Why: MarqIQ keeps one row per audience membership. Somebody in three audiences is three rows, exactly as they are three members in Mailchimp.
Fix: Compare against the total of every audience’s member count rather than against a single audience. The audience name is on every row, so you can split by audience to check one at a time.
Next steps
Related articles
Was this article helpful?