Mailchimp API v3 Wrapper

Common errors

• Error: "Unauthorized" (or HTTP Status 401)

  cause The Mailchimp API key provided during client instantiation is invalid or has insufficient permissions.
  fix Verify your Mailchimp API key is correct and has the necessary permissions for the requested operation. Ensure there are no leading/trailing spaces or typos.

• Error: "Resource Not Found" (or HTTP Status 404)

  cause The API path or an ID within the path (e.g., list ID, member ID) is incorrect or does not exist.
  fix Double-check the API path string and any IDs (e.g., list_id, member_id) against your Mailchimp account and the Mailchimp API documentation. Ensure IDs are URL-encoded if they contain special characters.

• TypeError: mailchimp.get is not a function

  cause The `Mailchimp` class constructor was called without the `new` keyword, or the `mailchimp` object was not correctly instantiated.
  fix Ensure you are instantiating the Mailchimp client correctly: `const mailchimp = new Mailchimp(apiKey);`.

• Error: connect ETIMEDOUT (or other network-related errors)

  cause The application could not establish a network connection to the Mailchimp API server, often due to firewall restrictions, proxy issues, or temporary network outages.
  fix Check your network connectivity, firewall settings, and any configured proxy settings. Ensure that your server or development environment can reach `api.mailchimp.com` over HTTPS (port 443).

Warnings

• gotcha Mailchimp API keys provide full access to your Mailchimp account. Never hardcode API keys directly in client-side code or commit them to version control. Always use environment variables or a secure configuration management system.
  Fix: Store your Mailchimp API key in an environment variable (e.g., `process.env.MAILCHIMP_API_KEY`) and load it at runtime. Ensure your `.env` files are in `.gitignore`.
• gotcha The `batch` operation defaults to `wait: true` and `unpack: true`. While convenient, for very large batch operations or slow Mailchimp processing times, this can lead to long-running requests that might exceed typical serverless function timeouts or client-side request limits. The client will poll Mailchimp until the batch is complete.
  Fix: For very large batches or time-sensitive operations, consider setting `wait: false` for the `batch` call and implementing your own polling logic using `mailchimp.batchWait(batchId)` later, or process results asynchronously via webhooks if supported by your application.
• gotcha The library primarily supports CommonJS `require()` syntax. While it might work with some bundlers or transpilers to enable `import` statements, official ESM support is not explicitly documented, which can lead to issues in modern Node.js environments configured for native ESM.
  Fix: For CommonJS-only environments (e.g., older Node.js projects), use `const Mailchimp = require('mailchimp-api-v3');`. For modern ESM projects, you might need to configure your build tool (like Webpack, Rollup, or Babel) to handle CommonJS modules, or use dynamic `import()` if available for specific use cases, though this is not idiomatic for class instantiation.
• gotcha The `path` parameter for `mailchimp.request` and shorthand methods (`get`, `post`, etc.) can be specified with or without path parameters. For example, `/lists/{list_id}` with `path_params: { list_id: 'abc' }` or directly as `/lists/abc`. Inconsistent usage can lead to API errors.
  Fix: Choose a consistent style for path specification. If using path parameters for clarity and reusability, always provide them in the `path_params` object when calling `mailchimp.request()`. For convenience methods like `get()`, it's often simpler to provide the fully resolved path string directly, e.g., `mailchimp.get('/lists/your_list_id')`.

Install

• npm install mailchimp-api-v3 npm
• yarn add mailchimp-api-v3 yarn
• pnpm add mailchimp-api-v3 pnpm

Imports

• Mailchimp
  wrong:

  import { Mailchimp } from 'mailchimp-api-v3';

  correct:

  const Mailchimp = require('mailchimp-api-v3');

  The library primarily uses CommonJS `require()` syntax as demonstrated in its documentation. Direct ES module `import` is not officially supported without a CommonJS wrapper or transpilation.
• Mailchimp class instantiation
  wrong:

  const mailchimp = Mailchimp(apiKey);

  correct:

  const mailchimp = new Mailchimp(apiKey);

  The `Mailchimp` symbol is a class constructor and must be instantiated with `new`.

Quickstart

Demonstrates initializing the Mailchimp client with an API key and fetching all audience lists using promise-based syntax.

const Mailchimp = require('mailchimp-api-v3');

const MAILCHIMP_API_KEY = process.env.MAILCHIMP_API_KEY ?? 'YOUR_MAILCHIMP_API_KEY'; // Replace with a real key or env var

if (MAILCHIMP_API_KEY === 'YOUR_MAILCHIMP_API_KEY') {
  console.warn('WARNING: Using placeholder Mailchimp API key. Set process.env.MAILCHIMP_API_KEY for real use.');
}

const mailchimp = new Mailchimp(MAILCHIMP_API_KEY);

async function getAudienceLists() {
  try {
    // Fetch all audience lists associated with the API key
    const result = await mailchimp.get('/lists');
    console.log('Successfully retrieved audience lists:');
    if (result && result.lists && result.lists.length > 0) {
      result.lists.forEach((list) => {
        console.log(`- ID: ${list.id}, Name: ${list.name}, Members: ${list.stats.member_count}`);
      });
    } else {
      console.log('No audience lists found.');
    }
  } catch (err) {
    console.error('Error fetching lists:', err.message);
    if (err.statusCode) {
      console.error('Mailchimp API Error Status:', err.statusCode);
      console.error('Mailchimp API Error Detail:', err.detail);
    } else {
      console.error('Network or other error:', err);
    }
  }
}

getAudienceLists();