batch_add_members

Add up to 500 subscribers to a Mailchimp audience in a single operation while preserving existing subscription statuses.

Instructions

Add multiple subscribers to a Mailchimp audience in one call. Handles up to 500 members per batch. Will not overwrite existing members' subscription status.

Input Schema

TableJSON Schema

Name	Required	Description
`list_id`	Yes	Audience/list ID
`members`	Yes	Array of contacts to add (max 500)
`update_existing`	No	Update merge fields for existing members (default false)

Implementation Reference

server.js:402-430 (handler)

The handler function for the batch_add_members tool, which processes the members array and calls mailchimp.lists.batchListMembers.

async ({ list_id, members, update_existing }) => {
  const batch = members.map((m) => ({
    email_address: m.email,
    status_if_new: "subscribed",
    merge_fields: {
      ...(m.first_name ? { FNAME: m.first_name } : {}),
      ...(m.last_name ? { LNAME: m.last_name } : {}),
    },
  }));
  const result = await mailchimp.lists.batchListMembers(list_id, {
    members: batch,
    update_existing: update_existing || false,
  });
  return {
    content: [
      {
        type: "text",
        text: JSON.stringify(
          {
            total_created: result.total_created,
            total_updated: result.total_updated,
            error_count: result.error_count,
            errors: result.errors.slice(0, 10).map((e) => ({ email: e.email_address, error: e.error })),
          },
          null,
          2
        ),
      },
    ],

server.js:386-401 (registration)

Registration of the batch_add_members tool with its schema definition in server.js.

server.tool(
  "batch_add_members",
  "Add multiple subscribers to a Mailchimp audience in one call. Handles up to 500 members per batch. Will not overwrite existing members' subscription status.",
  {
    list_id: z.string().describe("Audience/list ID"),
    members: z
      .array(
        z.object({
          email: z.string().describe("Email address"),
          first_name: z.string().optional().describe("First name"),
          last_name: z.string().optional().describe("Last name"),
        })
      )
      .describe("Array of contacts to add (max 500)"),
    update_existing: z.boolean().optional().describe("Update merge fields for existing members (default false)"),
  },

mailchimp-mcp