Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Mailchimp to Fondoo

Live3 min readUpdated

Mailchimp in Fondoo: what your AI agent can do with it, what to set up first, the permissions it needs and its limits.

In Mailchimp open Profile → Extras → API keys and create a key for Fondoo (the key ends in a data center such as -us21, which selects the API host); Mailchimp API keys carry the full permissions of the user who created them, so create it from a dedicated user with the Manager or Admin role and revoke it when you disconnect. Pass the audience (list) ID with each call; find it under Audience → Settings → Audience name and defaults. Fondoo only subscribes people who completed Fondoo's double opt-in and never re-subscribes anyone Mailchimp holds as unsubscribed, cleaned or archived. Free plans cannot send API-created campaigns to more than the plan allows; Mailchimp may refuse a send until the audience has the required address and permission reminder.

Official documentation: https://mailchimp.com/developer/marketing/api/

Use add_connection_key without fields for a signed, one-use secure paste page. Then call test_connection and inspect confirmed versus unknown permissions. Direct tool credentials carry a chat-log warning. list_connections never returns credentials.

Auth: api_key (Authorization: Bearer <key>; the key's -usNN suffix selects the host https://usNN.api.mailchimp.com/3.0). Category: email. Required provider scopes: none; Mailchimp API keys carry the permissions of the user that created them.

Capabilities are discoverable with list_connector_manifests; invoke them through connector_action. Writes retain shared Fondoo scopes, approvals, dry runs, audit, events and metering. Use rotate_connection_key before expiry and delete_connection to remove stored credentials; revoke upstream credentials separately.

What Fondoo does with Mailchimp

Fondoo operations sync_subscribers_to_provider, sync_subscribers_from_provider, create_provider_campaign and send_provider_campaign (REST POST /v1/ops/<name> and MCP call_tool) drive these normalized capabilities. Consent rules: only people who completed Fondoo's double opt-in are pushed as subscribed; Fondoo opt-outs are pushed as unsubscribed; anyone Mailchimp holds as unsubscribed, cleaned or archived is never re-subscribed and is adopted as an opt-out in Fondoo; imported members get a recorded consent attestation and still receive Fondoo's own confirmation email. send_provider_campaign is destructive, so agents need owner approval.

  • audiences.list (read): GET /lists (first 100) with memberCount from stats.member_count.
  • subscribers.list (read): GET /lists/{listId}/members with count/offset; the cursor is the next offset. listId is required. Status mapping: subscribed, pending, unsubscribed, cleaned; archived and transactional → other (never imported).
  • subscribers.upsert_batch (write): per member, PUT /lists/{listId}/members/{md5(email)} with status_if_new:"subscribed" and no status, so an existing member keeps whatever status Mailchimp holds. If the response says unsubscribed/cleaned/archived the outcome is skipped_provider_unsubscribed; tags are then added with POST .../tags. Unsubscribes read the member first (404 → unchanged, never created) and PATCH status:"unsubscribed". The PUT does not say whether the member existed, so a successful subscribe reports updated (with tags) or unchanged, never created. Up to 100 members and 220 requests per execute; 401/403/429 abort the batch, other failures are per-member error rows.
  • campaigns.create_draft (write): POST /campaigns (type:"regular", recipients.list_id, subject, preview text, title, sender) then PUT /campaigns/{id}/content with the HTML. If fromName/replyTo are missing the audience's campaign_defaults supply them. Nothing is sent.
  • campaigns.send (destructive): requires the campaign status save (draft) and GET /campaigns/{id}/send-checklist is_ready:true, then POST /campaigns/{id}/actions/send, or .../actions/schedule with schedule_time when scheduleAt is given. Mailchimp only accepts schedule times on the quarter hour (:00, :15, :30, :45), which Fondoo validates up front.

Vendor-native capabilities: members.get (by email), members.set_tags (add/remove), tags.list (tag-search), campaigns.list, campaigns.get.

Not implemented: member delete/archive (permanent delete cannot be undone), merge-field and interest-group writes, segments, automations, e-commerce, transactional (Mandrill).

API endpoints used

Limits and uncertainties

  • Rate limit: Mailchimp documents 10 simultaneous connections per user; Fondoo issues requests sequentially and budgets 10 executes per minute. 429 surfaces as rate_limited.
  • Verified from the Add-or-update-member page: status_if_new is required for new addresses and status is optional. Not documented there and therefore uncertain: that omitting status leaves an existing unsubscribed/cleaned member untouched (this is the documented upsert semantic, but it is not stated explicitly); the response status check is a second line of defence either way. Mailchimp also refuses to re-subscribe members in a compliance state through the API, which would surface as a per-member error.
  • Uncertain: exact send-checklist and schedule response shapes beyond is_ready and the 204 on success; the schedule endpoint is documented to require quarter-hour times, and free plans cannot schedule.
  • Uncertain: whether fields= filtering on GET /lists/{id}/members always returns total_items (used for the next-page decision; without it Fondoo pages until a short page).
  • Merge tags: campaign HTML uses *|UNSUB|*, Mailchimp's unsubscribe merge tag. Mailchimp rejects sending a campaign without its required footer content for the audience.