--- name: mailchimp description: "Operate Mailchimp Marketing audiences, campaigns, reports, automations, journeys, and Mailchimp Transactional/Mandrill email through SecretRef-backed helper requests." user-invocable: true requires: bins: - node credentials: - id: mailchimp-marketing-basic-auth kind: header required: true secret_ref: source: store id: MAILCHIMP_MARKETING_BASIC_AUTH scope: "Mailchimp Marketing API Authorization Basic header secret for https://.api.mailchimp.com/3.0" how_to_obtain: | Create a Mailchimp Marketing API key with the narrowest useful role for the account. Locally base64-encode `anystring:`. Set only that encoded credential as `MAILCHIMP_MARKETING_BASIC_AUTH` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set MAILCHIMP_MARKETING_BASIC_AUTH ""` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set MAILCHIMP_MARKETING_BASIC_AUTH ""`. Set `MAILCHIMP_SERVER_PREFIX` to the data-center suffix after the last hyphen, for example `us21` from a key ending in `-us21`. - id: mailchimp-marketing-oauth-token kind: bearer required: false secret_ref: source: store id: MAILCHIMP_MARKETING_OAUTH_TOKEN scope: "Mailchimp Marketing OAuth bearer token for https://login.mailchimp.com/oauth2/metadata and https://.api.mailchimp.com/3.0" how_to_obtain: | Complete Mailchimp's OAuth authorization flow outside this helper. Set the resulting access token as `MAILCHIMP_MARKETING_OAUTH_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set MAILCHIMP_MARKETING_OAUTH_TOKEN ""` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set MAILCHIMP_MARKETING_OAUTH_TOKEN ""`. Use helper commands with `--auth oauth`. - id: mandrill-api-key kind: api_key required: false secret_ref: source: store id: MANDRILL_API_KEY scope: "Mailchimp Transactional / Mandrill API key for https://mandrillapp.com/api/1.0" how_to_obtain: | In a Mailchimp account with Transactional Email provisioned, create a Transactional API key. Set `MANDRILL_API_KEY` through browser admin at `/admin/secrets`; if browser admin is unavailable, use `/secret set MANDRILL_API_KEY ""` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set MANDRILL_API_KEY ""`. config_variables: - id: mailchimp-server-prefix env: MAILCHIMP_SERVER_PREFIX required: true scope: "Mailchimp Marketing API data-center prefix used in https://.api.mailchimp.com/3.0" how_to_obtain: | Use the suffix after the last hyphen in a Mailchimp Marketing API key, such as `us21`, or the data-center prefix returned by the OAuth metadata flow. Store it in chat with `/env set MAILCHIMP_SERVER_PREFIX us21`. From a local terminal, use `hybridclaw env set MAILCHIMP_SERVER_PREFIX us21`. metadata: hybridclaw: category: marketing short_description: "Mailchimp audiences, campaigns, reports, journeys, and Mandrill transactional email." tags: - mailchimp - mandrill - email - marketing - campaigns related_roadmap: - R21.67 issue: 1136 stakes_tiers: green: - oauth.metadata - marketing.root - audience.list - audience.members - audience.member - audience.merge-fields - campaign.list - campaign.content-get - campaign.report - automation.list - automation.get - journey.list - journey.get - mandrill.message-info amber: - audience.member-upsert - audience.member-update - audience.member-archive - audience.tags-update - audience.merge-field-create - audience.merge-field-update - campaign.create - campaign.update - campaign.content-set red: - audience.bulk-plan - campaign.schedule - campaign.send - mandrill.send - mandrill.send-template escalation: writes: confirm-each route: f14 cost_measurement: system: UsageTotals sub_limit_key: mailchimp --- # Mailchimp Use this skill for Mailchimp Marketing and Mailchimp Transactional work: audience/list inspection, subscriber lookup and controlled mutations, tags, merge fields, campaign draft operations, campaign content, scheduling/sending, campaign reports, automation and journey readouts, and Mandrill transactional message lookup or sends. ## Default Workflow 1. Start with `credential-check` when setup is uncertain. The helper emits gateway-resolved `` and `` placeholders; it does not read runtime env or secret values itself. Missing `MAILCHIMP_SERVER_PREFIX`, `MAILCHIMP_MARKETING_BASIC_AUTH`, `MAILCHIMP_MARKETING_OAUTH_TOKEN`, or `MANDRILL_API_KEY` is surfaced by the gateway placeholder resolver or by a 401/403 upstream response. Do not run `hybridclaw secret list`, `hybridclaw env list`, `grep`, or local file inspection from the agent sandbox to decide whether Mailchimp values are configured; those checks can see the wrong runtime surface. For stored OAuth access tokens, use `oauth metadata --auth oauth` to retrieve the account-specific API endpoint and set `MAILCHIMP_SERVER_PREFIX` from the returned API endpoint host. 2. Use `mailchimp.cjs` noun/verb commands for live work. Normal commands send the helper-built request through the HybridClaw gateway `/api/http/request` path, so the gateway resolves `` and `` placeholders server-side. Use `--request` only for dry-run/debug output; do not normally reconstruct or relay `httpRequest` objects with the built-in `http_request` tool. 3. Treat `MAILCHIMP_MARKETING_BASIC_AUTH`, `MAILCHIMP_MARKETING_OAUTH_TOKEN`, and `MANDRILL_API_KEY` as SecretRefs only. Never ask the operator to paste tokens into chat, never print raw `Authorization` headers, and never include Mandrill keys in `--body-json`. 4. For audience writes, bulk subscriber plans, campaign draft/content writes, campaign schedule/send, and Mandrill sends, first run `approval-plan`, show the preview, and stop. After explicit operator approval for the named audience, campaign, or message target, run the approved helper command unchanged. 5. For 401 or 403, stop after the first failure and ask the operator to verify the token, user role, Transactional provisioning, and data-center prefix. Do not retry with broader permissions. 6. For 429, report rate-limit guidance from `Retry-After` or Mailchimp rate-limit headers when present. Do not start retry loops. 7. Minimize subscriber PII in summaries. Prefer subscriber hashes for lookup and archive/tag operations. Include email addresses only when required to create or update a member. ## Command Contract Use the standard helper shape: ```text node skills/mailchimp/mailchimp.cjs [--format json|pretty] [--request] [flags] node skills/mailchimp/mailchimp.cjs [--format json|pretty] approval-plan [flags] ``` ```bash node skills/mailchimp/mailchimp.cjs --help node skills/mailchimp/mailchimp.cjs --format json credential-check node skills/mailchimp/mailchimp.cjs --format json oauth metadata --auth oauth node skills/mailchimp/mailchimp.cjs --format json --request oauth metadata --auth oauth ``` Run Marketing reads: ```bash node skills/mailchimp/mailchimp.cjs --format json marketing root node skills/mailchimp/mailchimp.cjs --format json audience list --count 25 node skills/mailchimp/mailchimp.cjs --format json audience members --list-id --status subscribed node skills/mailchimp/mailchimp.cjs --format json audience member --list-id --email user@example.com node skills/mailchimp/mailchimp.cjs --format json audience merge-fields --list-id ``` Run guarded audience mutations only after approval: ```bash node skills/mailchimp/mailchimp.cjs --format json approval-plan audience member-upsert \ --list-id --email user@example.com --status-if-new pending \ --merge-fields-json '{"FNAME":"Ada"}' --tag customer:active node skills/mailchimp/mailchimp.cjs --format json approval-plan audience tags-update \ --list-id --email user@example.com --tag vip:active --tag stale:inactive node skills/mailchimp/mailchimp.cjs --format json approval-plan audience member-archive \ --list-id --email user@example.com node skills/mailchimp/mailchimp.cjs --format json approval-plan audience bulk-plan \ --list-id --operation member-upsert --count 2500 \ --source-label imports/2026-06-newsletter.csv \ --sample-json '{"email":"user@example.com","status_if_new":"pending","FNAME":"Ada"}' ``` Run campaign requests: ```bash node skills/mailchimp/mailchimp.cjs --format json campaign list --status save node skills/mailchimp/mailchimp.cjs --format json approval-plan campaign create --body-json '{"type":"regular","recipients":{"list_id":""},"settings":{"subject_line":"Subject","title":"Draft","from_name":"Team","reply_to":"team@example.com"}}' node skills/mailchimp/mailchimp.cjs --format json approval-plan campaign content-set --campaign-id --body-json '{"html":"

Hello

"}' node skills/mailchimp/mailchimp.cjs --format json approval-plan campaign schedule --campaign-id --schedule-time 2026-06-01T09:00:00+00:00 node skills/mailchimp/mailchimp.cjs --format json approval-plan campaign send --campaign-id ``` Run report and read-only automation/journey requests: ```bash node skills/mailchimp/mailchimp.cjs --format json campaign report --campaign-id --kind overview node skills/mailchimp/mailchimp.cjs --format json campaign report --campaign-id --kind bounces node skills/mailchimp/mailchimp.cjs --format json campaign report --campaign-id --kind opens node skills/mailchimp/mailchimp.cjs --format json campaign report --campaign-id --kind clicks node skills/mailchimp/mailchimp.cjs --format json campaign report --campaign-id --kind email-activity node skills/mailchimp/mailchimp.cjs --format json automation list node skills/mailchimp/mailchimp.cjs --format json journey list ``` Run Mandrill transactional requests: ```bash node skills/mailchimp/mailchimp.cjs --format json mandrill message-info --id node skills/mailchimp/mailchimp.cjs --format json approval-plan mandrill send --body-json '{"message":{"from_email":"ops@example.com","to":[{"email":"user@example.com","type":"to"}],"subject":"Receipt","text":"Thanks"}}' node skills/mailchimp/mailchimp.cjs --format json approval-plan mandrill send-template --body-json '{"template_name":"receipt","template_content":[],"message":{"to":[{"email":"user@example.com","type":"to"}],"merge":true}}' ``` Classify a saved or live error: ```bash node skills/mailchimp/mailchimp.cjs --format json classify-response --status 401 --body-json '{"title":"API Key Invalid"}' node skills/mailchimp/mailchimp.cjs --format json classify-response --gateway-error 'Stored secret MAILCHIMP_MARKETING_BASIC_AUTH is not set.' ``` ## Approval And Safety Boundaries Green operations are read-only inventory, lookup, report, automation, journey, and message-status calls. Amber operations mutate external Mailchimp state but do not send mail by themselves. Red operations can send or schedule external email and require explicit operator approval for the named campaign or message target. `--operator-grant` is an approval-workflow marker for this helper, not an access-control boundary. The gateway approval policy, network policy, and credential resolver remain the actual enforcement layers for external writes and sends. Bulk member mutation is intentionally exposed as a preview/approval boundary, not as a direct batch execution command. For more than one subscriber, run `approval-plan audience bulk-plan` with the target list, operation, source label, count, and a redacted sample row. After approval, generate exact per-member helper commands and run them with `--operator-grant`. Do not call Mailchimp batch endpoints from this skill. Unsupported destructive operations include permanent member deletion, campaign delete, audience delete, and Mandrill scheduled-message cancel/reschedule. The helper exposes archive and tag changes, not irreversible data deletion. ## Credential Notes Mailchimp Marketing uses `https://.api.mailchimp.com/3.0`, where `` is the data-center subdomain for the account. API keys usually include this as the suffix after the last hyphen. The helper defaults to `--auth api-key`, which uses `Authorization: Basic ` and `https://.api.mailchimp.com/3.0/...` so the gateway resolves both values server-side. Store the secret value as the base64 encoding of `anystring:`, not the raw API key in prompt text. OAuth access tokens are supported with `--auth oauth` and `Authorization: OAuth `. This skill uses an already stored OAuth access token; it does not perform the browser OAuth authorization flow itself. Use `oauth metadata --auth oauth` to read the OAuth token metadata endpoint and derive the account-specific data-center prefix before calling Marketing API endpoints. Mandrill requests place `key: ""` in the JSON body so the gateway performs placeholder replacement server-side. Do not include a `key` field in `--body-json`; the helper rejects it. ## Result Handling Base answers on successful live API results only. For setup failures, report which layer failed: missing `MAILCHIMP_SERVER_PREFIX`, gateway missing runtime secret, gateway policy denial, outbound network failure, Mailchimp 401/403, Mailchimp 429, or upstream validation error. Do not infer stale gateway state or network isolation without checking `hybridclaw gateway status`, logs, and the returned helper/gateway error body.