/mailchimp

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://<dc>.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:<api-key>`. 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 "<base64-user-colon-api-key>"`
      in browser `/chat` or TUI; local console fallback:
      `hybridclaw secret set MAILCHIMP_MARKETING_BASIC_AUTH "<base64-user-colon-api-key>"`.
      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://<dc>.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 "<oauth-token>"` in browser
      `/chat` or TUI; local console fallback:
      `hybridclaw secret set MAILCHIMP_MARKETING_OAUTH_TOKEN "<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 "<mandrill-key>"` in browser `/chat` or
      TUI; local console fallback:
      `hybridclaw secret set MANDRILL_API_KEY "<mandrill-key>"`.
config_variables:
  - id: mailchimp-server-prefix
    env: MAILCHIMP_SERVER_PREFIX
    required: true
    scope: "Mailchimp Marketing API data-center prefix used in https://<dc>.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 `<env:...>` and `<secret:...>` 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 `<env:...>` and `<secret:...>` placeholders server-side. Use `--request`