--- title: "Batch subscribe or unsubscribe" method: POST path: "/3.0/lists/{list_id}" tags: ["lists"] --- # Batch subscribe or unsubscribe `POST /3.0/lists/{list_id}` ## Request - Base URL: `https://api.mailchimp.com` - URL: `https://api.mailchimp.com/3.0/lists/{list_id}` - Auth: one of: - HTTP bearer - OAuth 2 - Authorization code: `https://login.mailchimp.com/oauth2/authorize` - Token URL: `https://login.mailchimp.com/oauth2/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Batch subscribe or unsubscribe list members. ## Path parameters - `list_id` string, required ## Query parameters - `skip_merge_validation` boolean - `skip_duplicate_check` boolean ## Request body - object: Members to subscribe to or unsubscribe from a list. - `members` union[], required: An array of objects, each representing an email address and the subscription status for a specific list. Up to 500 members may be added or updated with each API call. - union: Individuals who are currently or have been previously subscribed to this list, including members who have bounced or unsubscribed. - object - `email_address` string, nullable: Email address for a subscriber. - `email_type` string, nullable: Type of email this member asked to get ('html' or 'text'). - `interests` object, nullable: The key of this object's properties is the ID of the interest in question. - `ip_opt` string, nullable: The IP address the subscriber used to confirm their opt-in status. - `ip_signup` string, nullable: IP address the subscriber signed up from. - `language` string, nullable: If set/detected, the [subscriber's language](https://mailchimp.com/help/view-and-edit-contact-languages/). - `location` object, nullable: Subscriber location information. - `latitude` union: The location latitude. - number - string - `longitude` union: The location longitude. - number - string - `merge_fields` object, nullable: An individual merge var and value for a member. - `tags` string[], nullable: The tags that are associated with a member. - `status` 'subscribed' | 'unsubscribed' | 'cleaned' | 'pending' | 'transactional', nullable, required: Subscriber's current status. - `status_if_new` 'subscribed' | 'unsubscribed' | 'cleaned' | 'pending' | 'transactional', nullable: Subscriber's status udpated if they are net new. - `timestamp_opt` union: The date and time the subscriber confirmed their opt-in status in ISO 8601 format. - union - string - string - '' - `timestamp_signup` union: The date and time the subscriber signed up for the list in ISO 8601 format. - union - string - string - '' - `vip` boolean, nullable: [VIP status](https://mailchimp.com/help/designate-and-send-to-vip-contacts/) for subscriber. - object - `email_address` string, nullable: Email address for a subscriber. - `email_type` string, nullable: Type of email this member asked to get ('html' or 'text'). - `interests` object, nullable: The key of this object's properties is the ID of the interest in question. - `ip_opt` string, nullable: The IP address the subscriber used to confirm their opt-in status. - `ip_signup` string, nullable: IP address the subscriber signed up from. - `language` string, nullable: If set/detected, the [subscriber's language](https://mailchimp.com/help/view-and-edit-contact-languages/). - `location` object, nullable: Subscriber location information. - `latitude` union: The location latitude. - number - string - `longitude` union: The location longitude. - number - string - `merge_fields` object, nullable: An individual merge var and value for a member. - `tags` string[], nullable: The tags that are associated with a member. - `status` 'subscribed' | 'unsubscribed' | 'cleaned' | 'pending' | 'transactional', nullable: Subscriber's current status. - `status_if_new` 'subscribed' | 'unsubscribed' | 'cleaned' | 'pending' | 'transactional', nullable, required: Subscriber's status udpated if they are net new. - `timestamp_opt` union: The date and time the subscriber confirmed their opt-in status in ISO 8601 format. - union - string - string - '' - `timestamp_signup` union: The date and time the subscriber signed up for the list in ISO 8601 format. - union - string - string - '' - `vip` boolean, nullable: [VIP status](https://mailchimp.com/help/designate-and-send-to-vip-contacts/) for subscriber. - `sync_tags` boolean, nullable: Whether this batch operation will replace all existing tags with tags in request. - `update_existing` boolean, nullable: Whether this batch operation will change existing members' subscription status. ## Response `200` - object: Batch update list members. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` string: For GETs, this is a URL representing the schema that the response should conform to. - `error_count` integer: The total number of items matching the query, irrespective of pagination. - `errors` object[]: An array of objects, each representing an email address that could not be added to the list or updated and an error message providing more details. - `email_address` string: The email address that could not be added or updated. - `error` string: The error message indicating why the email address could not be added or updated. - `error_code` 'ERROR_CONTACT_EXISTS' | 'ERROR_GENERIC': A unique code that identifies this specifc error. - `field` string: If the error is field-related, information about which field is at issue. - `field_message` string: Message indicating how to resolve a field-related error. - `new_members` object[]: An array of objects, each representing a new member that was added to the list. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` string: For GETs, this is a URL representing the schema that the response should conform to. - `contact_id` string: A unique ID for the contact record. - `email_address` string: Email address for a subscriber. - `email_client` string: The list member's email client. - `email_type` string: Type of email this member asked to get ('html' or 'text'). - `id` string: The MD5 hash of the lowercase version of the list member's email address. - `interests` object: The key of this object's properties is the ID of the interest in question. - `ip_opt` string: The IP address the subscriber used to confirm their opt-in status. - `ip_signup` string: IP address the subscriber signed up from. - `language` string: If set/detected, the [subscriber's language](https://mailchimp.com/help/view-and-edit-contact-languages/). - `last_changed` string, date-time: The date and time the member's info was last changed in ISO 8601 format. - `last_note` object: The most recent Note added about this member. - `created_at` string, date-time: The date and time the note was created in ISO 8601 format. - `created_by` string: The author of the note. - `note` string: The content of the note. - `note_id` integer: The note id. - `list_id` string: The list id. - `location` object: Subscriber location information. - `country_code` string: The unique code for the location country. - `dstoff` integer: The offset for timezones where daylight saving time is observed. - `gmtoff` integer: The time difference in hours from GMT. - `latitude` number: The location latitude. - `longitude` number: The location longitude. - `timezone` string: The timezone for the location. - `member_rating` integer: Star rating for this member, between 1 and 5. - `merge_fields` object: An individual merge var and value for a member. - `stats` object: Open and click rates for this subscriber. - `avg_click_rate` number: A subscriber's average clickthrough rate. - `avg_open_rate` number: A subscriber's average open rate. - `status` 'subscribed' | 'unsubscribed' | 'cleaned' | 'pending' | 'transactional': Subscriber's current status. - `tags` object[]: The tags applied to this member. - `id` integer: The tag id. - `name` string: The name of the tag - `tags_count` integer: The number of tags applied to this member. - `timestamp_opt` string, date-time: The date and time the subscriber confirmed their opt-in status in ISO 8601 format. - `timestamp_signup` string, date-time: The date and time the subscriber signed up for the list in ISO 8601 format. - `unique_email_id` string: An identifier for the address across all of Mailchimp. - `vip` boolean: [VIP status](https://mailchimp.com/help/designate-and-send-to-vip-contacts/) for subscriber. - `total_created` integer: The total number of items matching the query, irrespective of pagination. - `total_updated` integer: The total number of items matching the query, irrespective of pagination. - `updated_members` object[]: An array of objects, each representing an existing list member whose subscription status was updated. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` string: For GETs, this is a URL representing the schema that the response should conform to. - `contact_id` string: A unique ID for the contact record. - `email_address` string: Email address for a subscriber. - `email_client` string: The list member's email client. - `email_type` string: Type of email this member asked to get ('html' or 'text'). - `id` string: The MD5 hash of the lowercase version of the list member's email address. - `interests` object: The key of this object's properties is the ID of the interest in question. - `ip_opt` string: The IP address the subscriber used to confirm their opt-in status. - `ip_signup` string: IP address the subscriber signed up from. - `language` string: If set/detected, the [subscriber's language](https://mailchimp.com/help/view-and-edit-contact-languages/). - `last_changed` string, date-time: The date and time the member's info was last changed in ISO 8601 format. - `last_note` object: The most recent Note added about this member. - `created_at` string, date-time: The date and time the note was created in ISO 8601 format. - `created_by` string: The author of the note. - `note` string: The content of the note. - `note_id` integer: The note id. - `list_id` string: The list id. - `location` object: Subscriber location information. - `country_code` string: The unique code for the location country. - `dstoff` integer: The offset for timezones where daylight saving time is observed. - `gmtoff` integer: The time difference in hours from GMT. - `latitude` number: The location latitude. - `longitude` number: The location longitude. - `timezone` string: The timezone for the location. - `member_rating` integer: Star rating for this member, between 1 and 5. - `merge_fields` object: An individual merge var and value for a member. - `stats` object: Open and click rates for this subscriber. - `avg_click_rate` number: A subscriber's average clickthrough rate. - `avg_open_rate` number: A subscriber's average open rate. - `status` 'subscribed' | 'unsubscribed' | 'cleaned' | 'pending' | 'transactional': Subscriber's current status. - `tags` object[]: The tags applied to this member. - `id` integer: The tag id. - `name` string: The name of the tag - `tags_count` integer: The number of tags applied to this member. - `timestamp_opt` string, date-time: The date and time the subscriber confirmed their opt-in status in ISO 8601 format. - `timestamp_signup` string, date-time: The date and time the subscriber signed up for the list in ISO 8601 format. - `unique_email_id` string: An identifier for the address across all of Mailchimp. - `vip` boolean: [VIP status](https://mailchimp.com/help/designate-and-send-to-vip-contacts/) for subscriber. ## Other responses - `default`: An error generated by the Mailchimp API. --- [API](https://skmtc.dev/mailchimp/apis/mailchimp-api.md) - [All operations](https://skmtc.dev/mailchimp/apis/mailchimp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mailchimp/apis/mailchimp-api/revisions/53bf4b156855?raw)