How to Use Batch Operations

With batch operations in the MailChimp API, you can complete more than one operation in just one call. For example, you might use a batch operation to add thousands of subscribers to a list, or to retrieve information about different campaigns. Batch operations run in the background on MailChimp’s servers. Clients can poll the API periodically to check batch status until they’re completed, or you can configure a batch webhook to be automatically alerted when a batch process completes.

Before You Start

To use batch operations in the MailChimp API, you only need to know how to make basic API calls. This guide doesn’t rely on any specific language or library.

Make a Batch Operations Request

The request you make to perform a batch operation is a list of calls to the API. For more information on making the request, view the request schema.

{
  "operations": [
  {
    "method": "GET", # The http verb for the operation
    "path": "/campaigns", # The relative path of the operation
    "operation_id": "my-id", # A string you provide that identifies the operation
    "params": {...}, # Any URL params, only used for GET 
    "body": "{...}" # The JSON payload for PUT, POST, or PATCH
  }, …
 ]
}

To trigger processing of a batch operations request, POST the request to /3.0/batches. As long as the request fits this format, you’ll receive a 200 response and a new batch operation resource will be returned.

{
  "id": "123abc", # Unique id of the batch call
  "status": "pending", # Status for the whole call
                       # Pending, preprocessing, started, finalizing, or finished
  "total_operations": 1, # Number of operations in the batch
  "finished_operations": 1, # Number of finished operations
  "errored_operations": 0, # Number of errored operations
  "submitted_at": "...", # Datetime the call was made
  "completed_at": "...", # Datetime when all the operations completed
  "response_body_url": "...", # URL to use to retrieve results
}

Here are some things to keep in mind when you make batch operation requests:

  • Operations in a request aren’t guaranteed to run in order.
  • GET requests that don’t include a count parameter will automatically page through the entire collection. This can be useful for retrieving an entire collection, but it may take a long time to process.

Note

The operation_id parameter in the batch request is optional and can be any string. The same operation_id that you supply in the request is returned with the results unchanged.

This means you can match a set of results to a specific operation in the original request, so we recommend using a unique and meaningful value for operation_id.

Check the Status of a Batch Operation

To retrieve the status of a batch operation that you have already requested, make a GET call to batches/{id} where the id is the string that was returned when the batch operation was originally requested. For a description of all the fields in the response, view the resource schema. Make a GET call to /3.0/batches to get a list of batch requested operations in the last 7 days.

The batch resource that’s returned will include these status indicators for recent operations:

  • pending Processing on the batch operation hasn’t started yet.
  • preprocessing The batch request is being broken up into smaller operations to speed up processing.
  • started Processing has started.
  • finalizing Processing has completed, but the results are being compiled and saved.
  • finished Processing is done. It’s now possible to retrieve the results from the URL listed in response_body_url.
  • total_operations The total number of operations to be processed.
  • finished_operations The number of operations that have processed.
  • errored_operations The number of operations that returned a non-200 response.

Get the Results of a Batch Operation

When processing is finished, get the results of the operations performed. For batch operations that consist only of POST or PATCH operations, like adding subscribers to a list, it’s not necessary to retrieve the results.

A GET call to the URL returned in the batch resources response_body_url returns a gzipped tar archive of JSON files that contain the results of operations in the following format:

[
    {
        "status_code": 200,
        "operation_id": "my-id",
        "response": "{...}"
    },...
]

Note

For security reasons, response_body_url is only valid for 10 minutes. After 10 minutes, generate another with a GET call to /3.0/batches/{id}.

After you make the batch operation request, results are available for 7 days.

Batch Webhooks

Configure a batch webhook to avoid the need to periodically check on batch statuses. A webhook allows you to specify a URL that will receive POST data from MailChimp once a batch process is completed.

To set up batch webhooks, use the Batch Webhooks API endpoint. We will validate any webhook URL by making a GET request to the provided address in order to ensure that it’s valid, so make sure that your URL can accept both GET and POST requests.

Once a batch webhook is configured, MailChimp will send information about completed batch operations to your webhook URL in a POST body of key/value pairs. This POST body will include the same response_body_url that’s returned in the response from GET /batches/{batch_id}, along with some additional information. Use this response_body_url to download the gzipped tar archive as normal, but please note that the same 10-minute expiration period applies. After 10 minutes, you can generate another reponse_body_url with a GET call to /3.0/batches/{id}.

Batch Webhook Sample Data

"data[_links][0][href]": "https://usX.api.mailchimp.com/3.0/batches"
"data[_links][0][method]": "GET"
"data[_links][0][rel]":  "parent"
"data[_links][0][schema]": "https://usX.api.mailchimp.com/schema/3.0/CollectionLinks/Batches.json"
"data[_links][0][targetSchema]": "https://usX.api.mailchimp.com/schema/3.0/Definitions/Batches/CollectionResponse.json"
"data[_links][1][href]": "https://usX.api.mailchimp.com/3.0/batches/1234ab56cd"
"data[_links][1][method]": "GET"
"data[_links][1][rel]":  "self"
"data[_links][1][targetSchema]": "https://usX.api.mailchimp.com/schema/3.0/Definitions/Batches/Response.json"
"data[_links][2][href]": "https://usX.api.mailchimp.com/3.0/batches/1234ab56cd"
"data[_links][2][method]": "DELETE"
"data[_links][2][rel]":  "delete"
"data[completed_at]":  "2017-02-10T14:44:22+00:00"
"data[errored_operations]":  "0"
"data[finished_operations]": "1"
"data[id]":  "1234ab56cd"
"data[response_body_url]": "https://mailchimp-api-batch.s3.amazonaws.com/1234ab56cd-response.tar.gz?AWSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Expires=1486739377&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxx%3D"
"data[status]":  "finished"
"data[submitted_at]":  "2017-02-10T14:44:14+00:00"
"data[total_operations]":  "1"
"fired_at":  "2017-02-10 14:59:37"
"type":  "batch_operation_completed"