Mailchimp Config Sync

A zero-config CLI tool for syncing configuration between Mailchimp audiences. Currently supports copying merge fields with an interactive selection interface.

Features

- Zero Configuration: No config files needed - just your API key
- Interactive Audience Selection: Browse and select audiences from a visual menu with member counts
- Interactive Field Selection: Choose which merge fields to copy with multi-select
- Smart Comparison: Automatically identifies which fields already exist in the target
- Pagination Support: Handles audiences with large numbers of merge fields
- Type Safe: Built with TypeScript for reliability
- No Live API Required for Tests: Comprehensive test suite with mocked API calls

Quick Start

$3

No installation needed! Run directly from GitHub:

``bash
npx github:DaveRobinson/mailchimp-config-sync merge-fields
`

$3

Clone and build from source:

`bash
git clone https://github.com/DaveRobinson/mailchimp-config-sync
cd mailchimp-config-sync
npm install
npm run build

Run locally


node dist/index.js merge-fields
`

Usage

$3

Run the CLI and follow the interactive prompts:

`bash
npx github:DaveRobinson/mailchimp-config-sync merge-fields
`

You'll be prompted for:
1. Your Mailchimp API key (hidden input)
2. Source audience (select from list)
3. Target audience (select from list)
4. Which merge fields to copy (multi-select)

$3

Pass your API key directly to skip the prompt:

`bash
npx github:DaveRobinson/mailchimp-config-sync merge-fields --api-key YOUR_API_KEY-us10
`

Or using the short form:

`bash
npx github:DaveRobinson/mailchimp-config-sync merge-fields -k YOUR_API_KEY-us10
`

$3

`bash
$ npx github:DaveRobinson/mailchimp-config-sync merge-fields

? Enter your Mailchimp API key: ••••••••••••••••••••••••••

Fetching audiences...
Found 3 audiences

? Select source audience:
❯ My Newsletter (1,234 members) - abc123
Product Updates (567 members) - def456
Beta Testers (89 members) - ghi789

? Select target audience:
❯ Product Updates (567 members) - def456
Beta Testers (89 members) - ghi789

Source: My Newsletter (abc123def)
Target: Product Updates (def456ghi)

Fetching merge fields...

Merge fields status:
✓ Already exists: FNAME (First Name) - text
✓ Already exists: LNAME (Last Name) - text
○ Available to copy: PHONE (Phone Number) - phone
○ Available to copy: BIRTHDAY (Birthday) - birthday
○ Available to copy: COMPANY (Company) - text

? Select merge fields to copy: (Space to select, Enter to confirm)
◉ PHONE - Phone Number (phone)
◯ BIRTHDAY - Birthday (birthday)
◉ COMPANY - Company (text)

Copying 2 merge field(s)...
✓ Created merge field: PHONE (Phone Number)
✓ Created merge field: COMPANY (Company)

✓ Successfully copied 2 merge field(s)
`

Getting Your Mailchimp API Key

1. Log in to your Mailchimp account
2. Go to Account > Extras > API Keys
3. Create a new API key or use an existing one
4. Your API key format will be: key-datacenter (e.g., abc123xyz-us10)

The datacenter (the part after the dash) is automatically extracted from your API key.

Note: This tool works with multiple audiences within the same Mailchimp account. Audiences are automatically fetched and displayed for selection - no need to manually look up IDs!

Development

$3

`bash
npm install
`

$3

`bash
npm run build
`

$3

Auto-rebuild on changes:

`bash
npm run dev
`

$3

`
src/
├── index.ts # CLI entry point with Commander
├── lists.ts # Audience/list fetching and selection
├── mailchimp-client.ts # Mailchimp API client wrapper
├── merge-fields.ts # Merge field operations
└── types.ts # TypeScript type extensions

test/
├── mocks/
│ └── mailchimp.ts # Mock factories for testing
├── lists.test.ts
├── mailchimp-client.test.ts
└── merge-fields.test.ts
`

Testing

Tests use vitest with comprehensive mocking - no live API key required.

$3

`bash


Run tests once

npm test

Watch mode

npm run test:watch

With coverage report

npm run test:coverage
`

$3

Current coverage: 97.56%

- 28 tests across 3 test suites
- All merge field and list operations tested
- Pagination, error handling, and edge cases covered
- Interactive selection flow fully tested

API

$3

The tool automatically handles:

- Pagination: Fetches all merge fields regardless of count
- Filtering: Excludes the default EMAIL field from copy operations
- Error Handling: Continues copying even if some fields fail
- Validation: Prevents duplicate fields in the target audience

$3

All Mailchimp merge field types are supported:
- text
- number
- address
- phone
- date
- url
- imageurl
- radio
- dropdown
- birthday
- zip

Limitations

- Currently only supports merge fields (not other audience settings)
- Does not copy field values, only field definitions
- Designed for copying between audiences in the same Mailchimp account
- Field comparison is based on tag names - use custom tag names for all merge fields

Troubleshooting

$3

`
Error: Invalid API key format. Expected format: key-server
`

Make sure your API key includes the datacenter suffix (e.g., -us10).

$3

If a field with the same tag already exists in the target audience, it will be marked as "Already exists" and skipped from the selection list.

License

MIT

Contributing

Contributions welcome! Please ensure tests pass before submitting PRs:

`bash
npm test
npm run build
``