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 npm:

npx @dave_robinson/mailchimp-config-sync merge-fields

Or compare tags between audiences:

npx @dave_robinson/mailchimp-config-sync compare-tags

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

Installation

Run with npx (No Installation)

npx @dave_robinson/mailchimp-config-sync merge-fields

Install Globally (Optional)

npm install -g @dave_robinson/mailchimp-config-sync

# Then run without npx
mailchimp-config-sync merge-fields
mailchimp-config-sync compare-tags

Usage

Basic Usage

Run the CLI and follow the interactive prompts:

npx @dave_robinson/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 CLI Arguments

Pass your API key and audience IDs directly:

npx @dave_robinson/mailchimp-config-sync merge-fields -k YOUR_API_KEY -s SOURCE_ID -t TARGET_ID

Or skip just the API key prompt:

npx @dave_robinson/mailchimp-config-sync merge-fields --api-key YOUR_API_KEY

Example Session

$ npx @dave_robinson/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 will include a datacenter suffix (e.g., abc123xyz456def-us7)

The datacenter suffix (the part after the dash) is automatically extracted and used to connect to the correct Mailchimp server.

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. It should look like: xxxxxxxxxx-xxxx (e.g., abc123xyz456def-us7).

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