Mailchimp
Mailchimp Batches API

The Batches API from Mailchimp — 2 operation(s) for batches.
Documentation GitHub OpenAPI
OpenAPI Specification

swagger: '2.0'
info:
  version: 3.0.55
  title: Mailchimp Marketing Abuse Batches API
  contact:
    name: Mailchimp API Support
    email: apihelp@mailchimp.com
  x-permalink: https://github.com/mailchimp/mailchimp-client-lib-codegen/blob/main/spec/marketing.json
  description: '

    The Mailchimp Marketing API provides programmatic access to Mailchimp data

    and functionality, allowing developers to build custom features to do

    things like sync email activity and campaign analytics with their

    database, manage audiences and campaigns, and more.'
host: server.api.mailchimp.com
basePath: /3.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
- application/problem+json
security:
- basicAuth: []
tags:
- name: Batches
paths:
  /batches:
    get:
      summary: Mailchimp List Batch Requests
      description: Get a summary of batch requests that have been made.
      operationId: getBatches
      parameters:
      - name: fields
        x-title: Fields
        in: query
        description: A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
        required: false
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - name: exclude_fields
        x-title: Exclude Fields
        in: query
        description: A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
        required: false
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - name: count
        x-title: Count
        in: query
        description: The number of records to return. Default value is 10. Maximum value is 1000
        required: false
        default: 10
        maximum: 1000
        type: integer
        example: example_value
      - name: offset
        x-title: Offset
        in: query
        description: Used for [pagination](https://mailchimp.com/developer/marketing/docs/methods-parameters/#pagination), this it the number of records from a collection to skip. Default value is 0.
        required: false
        default: 0
        type: integer
        example: example_value
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Batch Operations
            description: A summary of batch requests that have been made.
            properties:
              batches:
                type: array
                items:
                  type: object
                  title: Batch
                  description: The status of a batch request
                  properties:
                    id:
                      type: string
                      title: Batch ID
                      description: A string that uniquely identifies this batch request.
                      readOnly: true
                    status:
                      type: string
                      title: Status
                      description: The status of the batch call. [Learn more](https://mailchimp.com/developer/marketing/guides/run-async-requests-batch-endpoint/#check-the-status-of-a-batch-operation) about the batch operation status.
                      enum:
                      - pending
                      - preprocessing
                      - started
                      - finalizing
                      - finished
                      readOnly: true
                    total_operations:
                      type: integer
                      title: Total Operations
                      description: The total number of operations to complete as part of this batch request. For GET requests requiring pagination, each page counts as a separate operation.
                      readOnly: true
                    finished_operations:
                      type: integer
                      title: Finished Operations
                      description: The number of completed operations. This includes operations that returned an error.
                      readOnly: true
                    errored_operations:
                      type: integer
                      title: Error Operations
                      description: The number of completed operations that returned an error.
                      readOnly: true
                    submitted_at:
                      type: string
                      format: date-time
                      title: Submitted At
                      description: The date and time when the server received the batch request in ISO 8601 format.
                      readOnly: true
                    completed_at:
                      type: string
                      format: date-time
                      title: Completed At
                      description: The date and time when all operations in the batch request completed in ISO 8601 format.
                      readOnly: true
                    response_body_url:
                      type: string
                      title: Response Body URL
                      description: The URL of the gzipped archive of the results of all the operations.
                      readOnly: true
                    _links:
                      title: Links
                      description: A list of link types and descriptions for the API schema documents.
                      type: array
                      items:
                        type: object
                        title: Resource Link
                        description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                        properties:
                          rel:
                            type: string
                            title: Rel
                            description: As with an HTML 'rel' attribute, this describes the type of link.
                            readOnly: true
                          href:
                            type: string
                            title: Href
                            description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                            readOnly: true
                          method:
                            type: string
                            title: Method
                            description: The HTTP method that should be used when accessing the URL defined in 'href'.
                            enum:
                            - GET
                            - POST
                            - PUT
                            - PATCH
                            - DELETE
                            - OPTIONS
                            - HEAD
                            readOnly: true
                          targetSchema:
                            type: string
                            title: Target Schema
                            description: For GETs, this is a URL representing the schema that the response should conform to.
                            readOnly: true
                          schema:
                            type: string
                            title: Schema
                            description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                            readOnly: true
                      readOnly: true
                title: Batches
                description: An array of objects representing batch calls.
              total_items:
                type: integer
                title: Item Count
                description: The total number of items matching the query regardless of pagination.
                readOnly: true
              _links:
                title: Links
                description: A list of link types and descriptions for the API schema documents.
                type: array
                items:
                  type: object
                  title: Resource Link
                  description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                  properties:
                    rel:
                      type: string
                      title: Rel
                      description: As with an HTML 'rel' attribute, this describes the type of link.
                      readOnly: true
                    href:
                      type: string
                      title: Href
                      description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                      readOnly: true
                    method:
                      type: string
                      title: Method
                      description: The HTTP method that should be used when accessing the URL defined in 'href'.
                      enum:
                      - GET
                      - POST
                      - PUT
                      - PATCH
                      - DELETE
                      - OPTIONS
                      - HEAD
                      readOnly: true
                    targetSchema:
                      type: string
                      title: Target Schema
                      description: For GETs, this is a URL representing the schema that the response should conform to.
                      readOnly: true
                    schema:
                      type: string
                      title: Schema
                      description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                      readOnly: true
                readOnly: true
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Batches
      x-custom-config:
        methodNameSnake: list
        methodNameCamel: list
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Mailchimp Start Batch Operation
      description: Begin processing a batch operations request.
      operationId: postBatches
      parameters:
      - in: body
        name: body
        description: ''
        required: true
        schema:
          type: object
          required:
          - operations
          properties:
            operations:
              type: array
              title: Operations List
              description: An array of objects that describes operations to perform.
              items:
                type: object
                title: Operations
                required:
                - method
                - path
                properties:
                  method:
                    type: string
                    title: HTTP Method
                    description: The HTTP method to use for the operation.
                    enum:
                    - GET
                    - POST
                    - PUT
                    - PATCH
                    - DELETE
                    example: POST
                  path:
                    type: string
                    title: Path
                    description: The relative path to use for the operation.
                    example: /lists
                  params:
                    type: object
                    title: Query Parameters
                    description: 'Any request query parameters. Example parameters: {"count":10, "offset":0}'
                    example: '{"count":10,"offset":0}'
                  body:
                    type: string
                    title: Body
                    description: A string containing the JSON body to use with the request.
                    example: '{"title":"Test"}'
                  operation_id:
                    type: string
                    title: Operation ID
                    description: An optional client-supplied id returned with the operation results.
                    example: my-id-123
        example: example_value
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Batch
            description: The status of a batch request
            properties:
              id:
                type: string
                title: Batch ID
                description: A string that uniquely identifies this batch request.
                readOnly: true
              status:
                type: string
                title: Status
                description: The status of the batch call. [Learn more](https://mailchimp.com/developer/marketing/guides/run-async-requests-batch-endpoint/#check-the-status-of-a-batch-operation) about the batch operation status.
                enum:
                - pending
                - preprocessing
                - started
                - finalizing
                - finished
                readOnly: true
              total_operations:
                type: integer
                title: Total Operations
                description: The total number of operations to complete as part of this batch request. For GET requests requiring pagination, each page counts as a separate operation.
                readOnly: true
              finished_operations:
                type: integer
                title: Finished Operations
                description: The number of completed operations. This includes operations that returned an error.
                readOnly: true
              errored_operations:
                type: integer
                title: Error Operations
                description: The number of completed operations that returned an error.
                readOnly: true
              submitted_at:
                type: string
                format: date-time
                title: Submitted At
                description: The date and time when the server received the batch request in ISO 8601 format.
                readOnly: true
              completed_at:
                type: string
                format: date-time
                title: Completed At
                description: The date and time when all operations in the batch request completed in ISO 8601 format.
                readOnly: true
              response_body_url:
                type: string
                title: Response Body URL
                description: The URL of the gzipped archive of the results of all the operations.
                readOnly: true
              _links:
                title: Links
                description: A list of link types and descriptions for the API schema documents.
                type: array
                items:
                  type: object
                  title: Resource Link
                  description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                  properties:
                    rel:
                      type: string
                      title: Rel
                      description: As with an HTML 'rel' attribute, this describes the type of link.
                      readOnly: true
                    href:
                      type: string
                      title: Href
                      description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                      readOnly: true
                    method:
                      type: string
                      title: Method
                      description: The HTTP method that should be used when accessing the URL defined in 'href'.
                      enum:
                      - GET
                      - POST
                      - PUT
                      - PATCH
                      - DELETE
                      - OPTIONS
                      - HEAD
                      readOnly: true
                    targetSchema:
                      type: string
                      title: Target Schema
                      description: For GETs, this is a URL representing the schema that the response should conform to.
                      readOnly: true
                    schema:
                      type: string
                      title: Schema
                      description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                      readOnly: true
                readOnly: true
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Batches
      x-custom-config:
        methodNameSnake: start
        methodNameCamel: start
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /batches/{batch_id}:
    get:
      summary: Mailchimp Get Batch Operation Status
      description: Get the status of a batch request.
      operationId: getBatchesId
      parameters:
      - name: fields
        x-title: Fields
        in: query
        description: A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
        required: false
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - name: exclude_fields
        x-title: Exclude Fields
        in: query
        description: A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
        required: false
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - in: path
        name: batch_id
        type: string
        required: true
        description: The unique id for the batch operation.
        example: '500123'
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Batch
            description: The status of a batch request
            properties:
              id:
                type: string
                title: Batch ID
                description: A string that uniquely identifies this batch request.
                readOnly: true
              status:
                type: string
                title: Status
                description: The status of the batch call. [Learn more](https://mailchimp.com/developer/marketing/guides/run-async-requests-batch-endpoint/#check-the-status-of-a-batch-operation) about the batch operation status.
                enum:
                - pending
                - preprocessing
                - started
                - finalizing
                - finished
                readOnly: true
              total_operations:
                type: integer
                title: Total Operations
                description: The total number of operations to complete as part of this batch request. For GET requests requiring pagination, each page counts as a separate operation.
                readOnly: true
              finished_operations:
                type: integer
                title: Finished Operations
                description: The number of completed operations. This includes operations that returned an error.
                readOnly: true
              errored_operations:
                type: integer
                title: Error Operations
                description: The number of completed operations that returned an error.
                readOnly: true
              submitted_at:
                type: string
                format: date-time
                title: Submitted At
                description: The date and time when the server received the batch request in ISO 8601 format.
                readOnly: true
              completed_at:
                type: string
                format: date-time
                title: Completed At
                description: The date and time when all operations in the batch request completed in ISO 8601 format.
                readOnly: true
              response_body_url:
                type: string
                title: Response Body URL
                description: The URL of the gzipped archive of the results of all the operations.
                readOnly: true
              _links:
                title: Links
                description: A list of link types and descriptions for the API schema documents.
                type: array
                items:
                  type: object
                  title: Resource Link
                  description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                  properties:
                    rel:
                      type: string
                      title: Rel
                      description: As with an HTML 'rel' attribute, this describes the type of link.
                      readOnly: true
                    href:
                      type: string
                      title: Href
                      description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                      readOnly: true
                    method:
                      type: string
                      title: Method
                      description: The HTTP method that should be used when accessing the URL defined in 'href'.
                      enum:
                      - GET
                      - POST
                      - PUT
                      - PATCH
                      - DELETE
                      - OPTIONS
                      - HEAD
                      readOnly: true
                    targetSchema:
                      type: string
                      title: Target Schema
                      description: For GETs, this is a URL representing the schema that the response should conform to.
                      readOnly: true
                    schema:
                      type: string
                      title: Schema
                      description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                      readOnly: true
                readOnly: true
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Batches
      x-custom-config:
        methodNameSnake: status
        methodNameCamel: status
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: Mailchimp Delete Batch Request
      description: Stops a batch request from running. Since only one batch request is run at a time, this can be used to cancel a long running request. The results of any completed operations will not be available after this call.
      operationId: deleteBatchesId
      parameters:
      - in: path
        name: batch_id
        type: string
        required: true
        description: The unique id for the batch operation.
        example: '500123'
      responses:
        '204':
          description: Empty Response
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Batches
      x-custom-config:
        methodNameSnake: delete_request
        methodNameCamel: deleteRequest
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
securityDefinitions:
  basicAuth:
    type: basic
externalDocs:
  description: Learn more with the full Mailchimp API documentation.
  url: https://mailchimp.com/developer/marketing/
x-doc-structure:
  resources:
    root:
      title: API Root
      description: The API root resource links to all other resources available in the API. Calling the root directory also returns details about the Mailchimp user account.
      paths:
      - /
      subResources: []
    chimp-chatter:
      title: Chimp Chatter Activity
      description: Get the latest Chimp Chatter activity from your account.
      paths:
      - /activity-feed/chimp-chatter
    authorized-apps:
      title: Authorized Apps
      description: Manage registered, connected apps for your Mailchimp account with the Authorized Apps endpoints.
      paths:
      - /authorized-apps
      - /authorized-apps/{app_id}
    automation:
      title: Automations
      description: Mailchimp's classic automations feature lets you build a series of emails that send to subscribers when triggered by a specific date, activity, or event. Use the API to manage Automation workflows, emails, and queues. Does not include Customer Journeys.
      paths:
      - /automations
      - /automations/{workflow_id}
      - /automations/{workflow

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mailchimp/refs/heads/main/openapi/mailchimp-batches-api-openapi.yml
Mailchimp Batches API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
