{"id":16110,"library":"mailchimp-api-v3","title":"Mailchimp API v3 Wrapper","description":"The `mailchimp-api-v3` library, currently at version 1.15.0, provides a comprehensive Node.js wrapper for the Mailchimp API v3. It distinguishes itself by offering transparent handling of Mailchimp's batch operations, allowing developers to execute multiple API calls as a single logical unit with seamless polling and result unpacking. The library supports both traditional callback-based asynchronous programming and modern Promise-based patterns, enhancing flexibility for various project styles. It aims to simplify integration by closely mirroring the Mailchimp API v3 documentation structure, enabling direct mapping of API paths and parameters. While its release cadence isn't explicitly stated, version 1.15.0 indicates active development at some point. Its core value lies in abstracting away the complexities of batch request management and providing a consistent interface for the RESTful Mailchimp API. It is primarily used for server-side integration with Mailchimp services.","status":"active","version":"1.15.0","language":"javascript","source_language":"en","source_url":"https://thorning@github.com/thorning/node-mailchimp","tags":["javascript","mailchimp","api","v3","batch","mailchimp api v3","wrapper","mailchimp api"],"install":[{"cmd":"npm install mailchimp-api-v3","lang":"bash","label":"npm"},{"cmd":"yarn add mailchimp-api-v3","lang":"bash","label":"yarn"},{"cmd":"pnpm add mailchimp-api-v3","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { Mailchimp } from 'mailchimp-api-v3';","symbol":"Mailchimp","correct":"const Mailchimp = require('mailchimp-api-v3');"},{"note":"The `Mailchimp` symbol is a class constructor and must be instantiated with `new`.","wrong":"const mailchimp = Mailchimp(apiKey);","symbol":"Mailchimp class instantiation","correct":"const mailchimp = new Mailchimp(apiKey);"}],"quickstart":{"code":"const Mailchimp = require('mailchimp-api-v3');\n\nconst MAILCHIMP_API_KEY = process.env.MAILCHIMP_API_KEY ?? 'YOUR_MAILCHIMP_API_KEY'; // Replace with a real key or env var\n\nif (MAILCHIMP_API_KEY === 'YOUR_MAILCHIMP_API_KEY') {\n  console.warn('WARNING: Using placeholder Mailchimp API key. Set process.env.MAILCHIMP_API_KEY for real use.');\n}\n\nconst mailchimp = new Mailchimp(MAILCHIMP_API_KEY);\n\nasync function getAudienceLists() {\n  try {\n    // Fetch all audience lists associated with the API key\n    const result = await mailchimp.get('/lists');\n    console.log('Successfully retrieved audience lists:');\n    if (result && result.lists && result.lists.length > 0) {\n      result.lists.forEach((list) => {\n        console.log(`- ID: ${list.id}, Name: ${list.name}, Members: ${list.stats.member_count}`);\n      });\n    } else {\n      console.log('No audience lists found.');\n    }\n  } catch (err) {\n    console.error('Error fetching lists:', err.message);\n    if (err.statusCode) {\n      console.error('Mailchimp API Error Status:', err.statusCode);\n      console.error('Mailchimp API Error Detail:', err.detail);\n    } else {\n      console.error('Network or other error:', err);\n    }\n  }\n}\n\ngetAudienceLists();","lang":"javascript","description":"Demonstrates initializing the Mailchimp client with an API key and fetching all audience lists using promise-based syntax."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Mailchimp API key provided during client instantiation is invalid or has insufficient permissions.","error":"Error: \"Unauthorized\" (or HTTP Status 401)"},{"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.","cause":"The API path or an ID within the path (e.g., list ID, member ID) is incorrect or does not exist.","error":"Error: \"Resource Not Found\" (or HTTP Status 404)"},{"fix":"Ensure you are instantiating the Mailchimp client correctly: `const mailchimp = new Mailchimp(apiKey);`.","cause":"The `Mailchimp` class constructor was called without the `new` keyword, or the `mailchimp` object was not correctly instantiated.","error":"TypeError: mailchimp.get is not a function"},{"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).","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.","error":"Error: connect ETIMEDOUT (or other network-related errors)"}],"ecosystem":"npm"}