Batch subscribe or unsubscribe

POST

https://api.mailchimp.com/3.0/lists/:list_id

POST

/3.0/lists/:list_id

curl -X POST https://api.mailchimp.com/3.0/lists/list_id \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "members": [
    null
  ]
}'

200Successful

{
  "_links": [
    {
      "href": "string",
      "method": "GET",
      "rel": "string",
      "schema": "string",
      "targetSchema": "string"
    }
  ],
  "error_count": 42,
  "errors": [
    {
      "email_address": "string",
      "error": "string",
      "error_code": "ERROR_CONTACT_EXISTS",
      "field": "string",
      "field_message": "string"
    }
  ],
  "new_members": [
    {
      "_links": [
        {
          "href": "string",
          "method": "GET",
          "rel": "string",
          "schema": "string",
          "targetSchema": "string"
        }
      ],
      "contact_id": "string",
      "email_address": "string",
      "email_client": "string",
      "email_type": "string",
      "id": "string",
      "interests": {},
      "ip_opt": "string",
      "ip_signup": "string",
      "language": "string",
      "last_changed": "2024-01-15T09:30:00Z",
      "last_note": {
        "created_at": "2024-01-15T09:30:00Z",
        "created_by": "string",
        "note": "string",
        "note_id": 1
      },
      "list_id": "string",
      "location": {
        "country_code": "string",
        "dstoff": 1,
        "gmtoff": 1,
        "latitude": 1.1,
        "longitude": 1.1,
        "timezone": "string"
      },
      "member_rating": 1,
      "merge_fields": {},
      "stats": {
        "avg_click_rate": 1.1,
        "avg_open_rate": 1.1
      },
      "status": "subscribed",
      "tags": [
        {
          "id": 1,
          "name": "string"
        }
      ],
      "tags_count": 1,
      "timestamp_opt": "2024-01-15T09:30:00Z",
      "timestamp_signup": "2024-01-15T09:30:00Z",
      "unique_email_id": "string",
      "vip": true
    }
  ],
  "total_created": 42,
  "total_updated": 42,
  "updated_members": [
    {
      "_links": [
        {
          "href": "string",
          "method": "GET",
          "rel": "string",
          "schema": "string",
          "targetSchema": "string"
        }
      ],
      "contact_id": "string",
      "email_address": "string",
      "email_client": "string",
      "email_type": "string",
      "id": "string",
      "interests": {},
      "ip_opt": "string",
      "ip_signup": "string",
      "language": "string",
      "last_changed": "2024-01-15T09:30:00Z",
      "last_note": {
        "created_at": "2024-01-15T09:30:00Z",
        "created_by": "string",
        "note": "string",
        "note_id": 1
      },
      "list_id": "string",
      "location": {
        "country_code": "string",
        "dstoff": 1,
        "gmtoff": 1,
        "latitude": 1.1,
        "longitude": 1.1,
        "timezone": "string"
      },
      "member_rating": 1,
      "merge_fields": {},
      "stats": {
        "avg_click_rate": 1.1,
        "avg_open_rate": 1.1
      },
      "status": "subscribed",
      "tags": [
        {
          "id": 1,
          "name": "string"
        }
      ],
      "tags_count": 1,
      "timestamp_opt": "2024-01-15T09:30:00Z",
      "timestamp_signup": "2024-01-15T09:30:00Z",
      "unique_email_id": "string",
      "vip": true
    }
  ]
}

Batch subscribe or unsubscribe list members.

Authentication

AuthorizationBearer

Authorization using a Mailchimp API key (a.k.a. Bearer token)

AuthorizationBearer

Authorization using OAuth

Path parameters

list_idstringRequired

The unique ID for the list.

Query parameters

skip_merge_validationbooleanOptional

If skip_merge_validation is true, member data will be accepted without merge field values, even if the merge field is usually required. This defaults to false.

skip_duplicate_checkbooleanOptional

If skip_duplicate_check is true, we will ignore duplicates sent in the request when using the batch sub/unsub on the lists endpoint. The status of the first appearance in the request will be saved. This defaults to false.

Request

Members to subscribe to or unsubscribe from a list.

memberslist of anyRequired

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.

sync_tagsboolean or nullOptional

Whether this batch operation will replace all existing tags with tags in request.

update_existingboolean or nullOptional

Whether this batch operation will change existing members' subscription status.

Response

This endpoint returns an object.

_linkslist of objectsOptionalRead-only

A list of link types and descriptions for the API schema documents.

error_countintegerOptional

The total number of items matching the query, irrespective of pagination.

errorslist of objectsOptional

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.

new_memberslist of objectsOptional

An array of objects, each representing a new member that was added to the list.

total_createdintegerOptional

The total number of items matching the query, irrespective of pagination.

total_updatedintegerOptional

The total number of items matching the query, irrespective of pagination.

updated_memberslist of objectsOptional

An array of objects, each representing an existing list member whose subscription status was updated.