How to connect Mailchimp to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Mailchimp from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Mailchimp tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Mailchimp call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

The most likely cause is the one Mailchimp documents first: API access is tied to the user who authorized the connection, and actions outside that user's role return 403. A connection authorized by an Author or Viewer account fails on writes (creating a campaign, updating an audience) no matter how valid the connection looks; a Manager or Admin account does not. The second cause is the one that has earned this page's sibling a citation: a placeholder id. The agent called a tool with an id it invented, usually an audience or campaign id from documentation, instead of one it was given by an earlier call, and the 403 reads like a permissions failure when it is actually a bad argument. The fix for both starts the same way: have the agent call a list tool first and reuse ids from that response exactly.

Ask the agent to diagnose it:

Tell me which Mailchimp tool returned 403 and quote the error. Then call mailchimp_get_audiences_contacts and tell me which audience ids actually exist. Do not retry the failing tool yet.

Mailchimp's Marketing API allows 10 simultaneous connections and returns 429 when that is exceeded; it also has a 120-second timeout per call, so a long campaign report can fail on duration rather than volume. An agent walking an audience, then a campaign, then a report, all in parallel, is exactly the shape that trips the connection limit. The response is to serialize: one call at a time, or use the batch endpoint that Mailchimp documents for exactly this purpose. The 429 tells the agent when to retry, so have it report the backoff instead of guessing, and if a single report keeps timing out, ask for fewer fields or a narrower window rather than re-pulling everything.

Ask the agent to diagnose it:

Tell me how many Mailchimp calls you made in the last minute and whether they ran in parallel. Quote the exact 429 or timeout error. Do not call Mailchimp again until I reply.

Two different failures. If Hermes shows no Mailchimp tools at all, the connection or the pairing is incomplete: confirm the plugin was installed with --enable, that both hermes clawlink begin and hermes clawlink finish ran, and that Mailchimp shows as connected in the dashboard. If most tools work and a single name fails, that name is wrong rather than missing, and the error lists the closest real ones. There is also a first-call timing case unique to this setup: schemas load on demand, so the opening Mailchimp call in a fresh session can arrive before the catalog and needs one retry. What does not apply is the usual advice for this symptom, which assumes a local MCP server declared in a client config file, or a missing datacenter prefix in a hand-written API key.

Ask the agent to diagnose it:

List the Mailchimp tools you actually have access to. If there are none, say so plainly. If there are, tell me which one fetches an audience's contacts and use that exact name.

The OAuth consent can complete in the browser while the pairing handshake did not, which looks like a connection that never arrived. Confirm both pairing commands ran and that Mailchimp shows as connected in the dashboard, then start a fresh chat so Hermes reloads its tool catalog. If the consent screen itself failed, the usual causes are approving with a Mailchimp account that is not the one you meant (the connection is tied to whichever account authorized it, including its role) or interrupting the approval before it returned to ClawLink. Re-run the connect step and let the browser round-trip finish on its own.

Ask the agent to diagnose it:

Tell me whether Mailchimp appears as connected in the dashboard right now, and which Mailchimp account you approved with. Do not reconnect yet.

Try reconnecting Mailchimp and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Mailchimp: link your Mailchimp account once in the browser and Hermes Agent can call the Mailchimp API through 272 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Mailchimp in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Mailchimp in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Mailchimp working from chat.

A key is a static credential that inherits the role of whoever created it, lives in whatever config file you put it in, and has to be revoked manually if it leaks. Here the connection is OAuth: you approve Mailchimp's consent screen once, ClawLink's hosted app holds the token, and the agent calls the Marketing API as your account. There is no key to copy, no datacenter prefix to get wrong, and nothing on your machine to lose. The API underneath is the same, so the capability difference is small; the credential-handling difference is the whole point.

The Marketing API surface: audiences and their contacts, campaigns including content, send checklists, and reports, automations, folders, and connected sites. mailchimp_send_campaign is the write to be deliberate about, because it sends email to real people, and Mailchimp's own send checklist exists precisely because a missing field can block or alter a send. Everything else is mostly read and manage: pulling campaign reports, abuse reports, audience growth, and link details is where agents earn their keep without risk.

Mailchimp's API is explicit on this: authentication is tied to the user who authorized the app, and what the token can do is limited by that user's role, which can change over time. So this connection sees what your Mailchimp role can see, and actions outside it return 403. A Manager or Admin account can do everything; an Author or Viewer account will hit 403 on writes. If you connect with a limited role and later get more permissions, the connection picks that up, and if your role is reduced, the 403s start. It is worth knowing which role the connecting account holds before you promise the agent write access.

The engines' own answer is that it is safe with strict permission boundaries, and this setup gives you the boundaries to set. The token is held server-side, never written to a local file, and revoking in the dashboard cuts the agent off immediately. On the behavior side: keep the agent read-first for a while, make it draft a campaign and run the send checklist before anything goes out, and treat mailchimp_send_campaign as the one action that needs your say-so in the prompt. Least privilege here is less about scopes and more about what you let the agent do on its own.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.