Mailchimp

This connector reaches the Mailchimp Marketing API v3.0 and pins your account's host, so an agent can read your audiences, look up members, list campaigns and pull the report for a campaign that has already gone out. Two writes are included and both start switched off: adding or updating a member, and sending a campaign.

Change the data centre before you install

Mailchimp gives every account its own host, https://<dc>.api.mailchimp.com/3.0. The manifest ships with us1 as a placeholder. Edit base_url to your own data centre before installing, or every call will fail against the wrong account.

To find yours, log in to Mailchimp and look at the browser URL: in https://us19.admin.mailchimp.com/ the server prefix is us19. It is also the suffix of your API key, after the final dash.

What you need

A Mailchimp API key. In Mailchimp, open your profile icon, then Profile → Extras → API keys → Create A Key. The full key is shown once and never again, so copy it straight away.

Mailchimp API keys have no scopes. The key inherits the permissions of the account user who generated it, so least privilege is a decision you make in Mailchimp's user settings, not at connection time. Only the Owner, an Admin or a Manager can generate a key at all — Author and Viewer accounts have no access to API keys — so the least-privileged option available is a key generated by a Manager. Give the key its own name so you can revoke it without disturbing anything else. Mailchimp keys do not expire.

The connector authenticates with HTTP Basic, where Mailchimp expects any username and the key as the password. Paste the credential in exactly this form, as one line:

anystring:abc123def456abc123def456abc123de-us19

The literal word anystring is fine — Mailchimp ignores the username. Everything after the colon is your key, including its -us19 suffix. Permaura seals the whole string on your gateway and injects it server-side; you cannot read it back afterwards.

OAuth is not the path here — the API key is

Mailchimp also supports OAuth 2, and the manifest carries its endpoints (https://login.mailchimp.com/oauth2/authorize and .../oauth2/token). From gateway 1.1.0 Permaura can run a bring-your-own-app authorisation code flow for the connectors that need one: you register your own OAuth app with the provider, the gateway performs the code exchange itself, seals the tokens on your own machine and keeps them refreshed from then on. permaura.com is never involved and never sees any of it.

That flow cannot complete for Mailchimp, and nothing here needs it to. Mailchimp issues a single non-expiring access token and no refresh token at all. The gateway refuses to seal a credential when the provider returns no refresh token, rather than storing one that could quietly die later — so POST /v1/connections/:id/oauth/start will hand you an authorisation link and let you approve it in the browser, then stop at the callback with that error.

Nothing is lost by it. A Mailchimp API key does not expire either, and carries the permissions of the user who generated it, so the key is both the supported path and the equivalent one.

Add the connection

1. Open Access → Connections in the console and choose Add connection.
2. Pick Mailchimp from the catalog.
3. Paste the anystring:<your-api-key> line as the credential. You supply it once, at creation.
4. Save. The connection appears with its capabilities listed, reads on and writes off.

Adding the connection makes these actions possible, not permitted — an agent still needs a grant before it can call any of them.

Check it works by having an agent call api.ping. It hits the API without touching account data, so a success there means the host and the credential are both right.

What the agent can do

Action	What it does	On by default
api.ping	Health check for the API and the credential	Yes
audiences.list	Lists your audiences, optionally sorted by creation date	Yes
audiences.read	Reads one audience, optionally with its total contact count	Yes
members.list	Lists members of an audience, filterable by status	Yes
members.read	Reads one member of an audience	Yes
campaigns.list	Lists campaigns, filterable by type, status and audience	Yes
campaigns.read	Reads a campaign's settings and metadata	Yes
reports.read	Reads the report for a sent campaign: opens, clicks, bounces	Yes
members.upsert	Adds a member to an audience, or updates one that already exists	No
campaigns.send	Sends a campaign to the recipients it was set up for	No, and needs approval

campaigns.send is deliberately the strictest thing here. It is classified critical and gated on a human approval, because a send cannot be recalled: an agent that calls it gets awaiting approval back and the mail only goes out once you approve on your device.

Responses are redacted before the agent sees them. email_address, full_name, merge_fields, unique_email_id, ip_signup, ip_opt, location, phone and address are stripped, so an agent can count and segment your audience without harvesting it.

Good to know

• No deletes. Deleting an audience, a campaign or a member permanently is not in this connector at all. If you need one, add it deliberately rather than expecting it in the catalog set.
• subscriber_hash is not the email. Member endpoints take the MD5 hash of the lowercased email address. Mailchimp also accepts the plain email address or the contact_id in that position, which is usually easier for an agent.
• members.upsert really is an upsert. A PUT with an unknown hash creates the member using status_if_new; with a known one it updates them, status and merge fields included. It cannot resurrect an unsubscribed contact — Mailchimp rejects that with a compliance-state error — but it can add new contacts against your paid contact allowance, and it can unsubscribe an existing one. That is why it starts disabled.
• Rate limits. Mailchimp allows 10 simultaneous connections per account and times a call out at 120 seconds. Beyond that you get a 429, or under sustained load a bare 403 with no JSON body — which looks like an auth failure but is not. Batch reads with count and offset rather than firing requests in parallel; count defaults to 10 and maxes out at 1000.
• No sandbox. Mailchimp does not publish a test environment for the Marketing API, so every call here lands on your live account. If you want to rehearse members.upsert, make a throwaway audience first.
• Sending has its own limits. Your Mailchimp plan caps sends and contacts independently of the API. campaigns.send will fail if the campaign is not fully set up, or if you are over your plan's allowance. It also takes no parameters beyond the campaign id, so an agent can only send something a person already composed and configured in Mailchimp.
• RSS campaigns are the one exception to "immediate". Everything else goes out the moment the call succeeds; an RSS campaign starts following its own schedule instead. Either way the call is not reversible, which is why it is approval-gated.
• One host per connection. The connection can only ever reach the base_url you pinned. If you manage two Mailchimp accounts on different data centres, create two connections.