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

Run with npx (Recommended)

No installation needed! Run directly from GitHub:

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

Local Development

Clone and build from source:

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

Basic Usage

Run the CLI and follow the interactive prompts:

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)

With API Key Parameter

Pass your API key directly to skip the prompt:

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

Or using the short form:

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

Example Session

$ 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

Setup

npm install

Build

npm run build

Watch Mode

Auto-rebuild on changes:

npm run dev

Project Structure

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.

Run Tests

# Run tests once
npm test

# Watch mode
npm run test:watch

# With coverage report
npm run test:coverage

Test Coverage

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

Merge Fields Operations

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

Supported Merge Field Types

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

Invalid API Key Format

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

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

Field Already Exists

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:

npm test
npm run build