---
name: iblai-connect-mailchimp
description: "Read and write Mailchimp data through the Mailchimp Marketing API and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Mailchimp data, or to set up a Mailchimp MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Mailchimp connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/mailchimp — not part of the iblai/vibe repository. Checked against Mailchimp's documentation on October 20, 2026; test it against your own Mailchimp setup before you rely on it.

Email marketing platform. A Mailchimp account holds audiences (lists) and their contacts with subscription status, tags and segments, plus campaigns, templates, automations and campaign reports.

## Auth & conventions

- **API:** Mailchimp Marketing API (REST). REST API (version 3.0) for audiences/lists, list members, tags, segments, campaigns, campaign content and reports, plus a Batch endpoint for long-running bulk work. Lists use count (max 1,000) and offset paging.
- **Base URL:** https://api.mailchimp.com/3.0/
- **Access:** Public, self-serve. Account users authenticate with a Mailchimp API key. Apps that act for other Mailchimp users register an OAuth app in the Registered Apps dashboard and store the client secret securely.
- **Auth:** API key (HTTP Basic); OAuth 2.0 authorization code. With an API key, send Basic auth with any string as the username and the key as the password. OAuth apps send users to https://login.mailchimp.com/oauth2/authorize and exchange the code at https://login.mailchimp.com/oauth2/token.
- **Limits:** 10 simultaneous connections per user (not per key); over that returns HTTP 429. Calls time out after 120 seconds; use the Batch endpoint for long work. Paging: count default 10, max 1,000, with offset.
- Keep Mailchimp credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Audiences (lists)** — Lists endpoint returns audiences with stats and settings.
- **List members** — Members of an audience with email, subscription status, merge fields and tags.
- **Campaigns** — GET /campaigns lists campaigns with status, settings and send time; count and offset paging.
- **Reports** — Campaign reports: opens, clicks, bounces and unsubscribes.
- **Ping** — GET /ping is a health check that confirms credentials without changing the account.

## Writes

- **Add or update contact** — Add or update a list member, including subscription status and tags.
- **Create campaign** — Create a campaign and set its content and audience.
- **Send campaign** — Send or schedule a campaign to an audience; emails go out to real recipients. **Confirm with the user first.**
- **Batch operations** — Submit many operations as one asynchronous Batch request.

## Expose it to an ibl.ai agent (MCP)

Mailchimp publishes an official MCP server, Mailchimp developer docs MCP server (https://mailchimp.com/developer/marketing/build/ai-tools/mcp-server). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - Mailchimp supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "How many contacts joined our main Mailchimp audience last month?"
- "Show open and click rates for our last five campaigns"
- "Tag every subscriber who clicked the spring sale email with spring-buyer"
- "Draft a campaign to the VIP segment but do not send it"

## Guardrails

- Holds consumer contact data and marketing consent (subscription status, opt-in records). Sending must respect unsubscribe and consent rules such as CAN-SPAM and GDPR.
- Request the narrowest Mailchimp scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Mailchimp Marketing API quick start: https://mailchimp.com/developer/marketing/guides/quick-start/
- Mailchimp OAuth 2 guide: https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/
- Mailchimp MCP server: https://mailchimp.com/developer/marketing/build/ai-tools/mcp-server
- Mailchimp developer docs MCP server: https://mailchimp.com/developer/marketing/build/ai-tools/mcp-server
- This connector on ibl.ai: https://ibl.ai/developer/connectors/mailchimp
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections