Mailchimp Contacts API
The contacts API from Mailchimp — 6 operation(s) for contacts.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/mailchimp-contacts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
version: 3.0.91
title: Mailchimp Marketing Contacts 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
servers:
- url: https://server.api.mailchimp.com/3.0
security:
- basicAuth: []
tags:
- name: contacts
paths:
/audiences:
get:
summary: Get a list of audiences
description: Get information about all audiences in the account.
operationId: getAudienceContacts
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
style: form
explode: false
schema:
type: array
items:
type: string
- 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
style: form
explode: false
schema:
type: array
items:
type: string
- name: count
x-title: Count
in: query
description: The number of records to return. Default value is 10. Maximum value is 1000
required: false
schema:
type: integer
default: 10
maximum: 1000
- name: offset
x-title: Offset
in: query
description: Used for [pagination](https://mailchimp.com/developer/marketing/docs/methods-parameters/#pagination), this is the number of records from a collection to skip. Default value is 0.
required: false
schema:
type: integer
default: 0
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
description: An array of objects, each representing an audience record.
properties:
audiences:
title: Audiences
description: An array of objects, each representing an audience record.
type: array
items:
type: object
description: An instance of an audience.
properties:
id:
type: string
title: Audience ID
description: The unique ID for the audience.
example: 773280e405
name:
type: string
title: Audience Name
description: The name of an audience
example: Example Audience
stats:
type: object
title: Audience Stats
properties:
total_contacts:
type: integer
title: Contact Count
description: The total count of all contacts in an audience
readOnly: true
enabled_channels:
type: array
title: Enabled Channels
description: The communication channels enabled on an audience
items:
type: string
total_items:
type: integer
title: Item Count
description: The total number of items matching the query regardless of pagination.
readOnly: true
application/problem+json:
schema:
type: object
description: An array of objects, each representing an audience record.
properties:
audiences:
title: Audiences
description: An array of objects, each representing an audience record.
type: array
items:
type: object
description: An instance of an audience.
properties:
id:
type: string
title: Audience ID
description: The unique ID for the audience.
example: 773280e405
name:
type: string
title: Audience Name
description: The name of an audience
example: Example Audience
stats:
type: object
title: Audience Stats
properties:
total_contacts:
type: integer
title: Contact Count
description: The total count of all contacts in an audience
readOnly: true
enabled_channels:
type: array
title: Enabled Channels
description: The communication channels enabled on an audience
items:
type: string
total_items:
type: integer
title: Item Count
description: The total number of items matching the query regardless of pagination.
readOnly: true
default:
description: An error generated by the Mailchimp API.
content:
application/json:
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
application/problem+json:
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:
- contacts
x-custom-config:
methodNameSnake: list_audiences
methodNameCamel: listAudiences
/audiences/{audience_id}:
get:
summary: Get audience info
description: Get information about a specific audience.
operationId: getAudienceId
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
style: form
explode: false
schema:
type: array
items:
type: string
- 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
style: form
explode: false
schema:
type: array
items:
type: string
- name: audience_id
x-title: Audience ID
in: path
description: The unique ID for the audience.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
description: An instance of an audience.
properties:
id:
type: string
title: Audience ID
description: The unique ID for the audience.
example: 773280e405
name:
type: string
title: Audience Name
description: The name of an audience
example: Example Audience
stats:
type: object
title: Audience Stats
properties:
total_contacts:
type: integer
title: Contact Count
description: The total count of all contacts in an audience
readOnly: true
enabled_channels:
type: array
title: Enabled Channels
description: The communication channels enabled on an audience
items:
type: string
application/problem+json:
schema:
type: object
description: An instance of an audience.
properties:
id:
type: string
title: Audience ID
description: The unique ID for the audience.
example: 773280e405
name:
type: string
title: Audience Name
description: The name of an audience
example: Example Audience
stats:
type: object
title: Audience Stats
properties:
total_contacts:
type: integer
title: Contact Count
description: The total count of all contacts in an audience
readOnly: true
enabled_channels:
type: array
title: Enabled Channels
description: The communication channels enabled on an audience
items:
type: string
default:
description: An error generated by the Mailchimp API.
content:
application/json:
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
application/problem+json:
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:
- contacts
x-custom-config:
methodNameSnake: get_audience_id
methodNameCamel: getAudienceId
/audiences/{audience_id}/contacts:
get:
summary: Get Contacts
description: Get a list of omni-channel contacts for a given audience.
operationId: getAudienceContactList
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
style: form
explode: false
schema:
type: array
items:
type: string
- 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
style: form
explode: false
schema:
type: array
items:
type: string
- name: count
x-title: Count
in: query
description: The number of records to return. Default value is 10. Maximum value is 1000
required: false
schema:
type: integer
default: 10
maximum: 1000
- name: cursor
x-title: cursor
in: query
description: Paginate through a collection of records by setting the `cursor` parameter to a `next_cursor` attribute returned by a previous request. Default value fetches the first "page" of results.
required: false
schema:
type: string
- name: created_before
x-title: Created Before Time
in: query
description: 'Restricts the response to contacts created at or before the specified time (inclusive). Uses ISO 8601 format: 2025-04-23T15:41:36+00:00.'
required: false
schema:
type: string
format: date-time
- name: created_since
x-title: Created Since Time
in: query
description: 'Restricts the response to contacts created after the specified time (exclusive). Uses ISO 8601 format: 2025-04-23T15:41:36+00:00.'
required: false
schema:
type: string
format: date-time
- name: updated_before
x-title: Updated Before Time
in: query
description: 'Restricts the response to contacts updated at or before the specified time (inclusive). Uses ISO 8601 format: 2025-04-23T15:41:36+00:00.'
required: false
schema:
type: string
format: date-time
- name: updated_since
x-title: Updated Since Time
in: query
description: 'Restricts the response to contacts updated after the specified time (exclusive). Uses ISO 8601 format: 2025-04-23T15:41:36+00:00.'
required: false
schema:
type: string
format: date-time
- name: audience_id
x-title: Audience ID
in: path
description: The unique ID for the audience.
required: true
schema:
type: string
- name: sort_field
x-title: Sort By Field
description: Specifies the field to sort the returned contacts by.
in: query
required: false
schema:
type: string
enum:
- created_at
- updated_at
- name: sort_dir
x-title: Sort Direction
description: Determines the order direction for sorted results.
in: query
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
description: An array of objects, each representing a contact record.
properties:
contacts:
title: Contacts
description: An array of objects, each representing a contact record.
type: array
items:
type: object
description: An instance of a contact.
properties:
id:
type: string
title: Contact ID
description: The unique ID for the contact.
example: 7CCF816ADF6CE1B11AE09BB024A02B9B
readOnly: true
audience_id:
type: string
title: Audience ID
description: The unique ID for the audience.
example: 773280e405
readOnly: true
language:
type: string
title: Language
description: The subscribers detected language. Empty string when no language has been detected or set.
enum:
- ''
- en
- ar
- af
- be
- bg
- ca
- zh
- zh_CN
- hr
- cs
- da
- nl
- et
- fa
- fi
- fr
- fr_CA
- de
- el
- he
- hi
- hu
- is
- id
- ga
- it
- ja
- km
- ko
- lv
- lt
- mt
- ms
- mk
- 'no'
- pl
- pt
- pt_PT
- ro
- ru
- sr
- sk
- sl
- es
- es_ES
- sw
- sv
- ta
- th
- tr
- uk
- vi
example: en
status:
type: string
title: Status
description: The status of a contact.
enum:
- active
- archived
example: active
readOnly: true
email_channel:
type: object
title: Email Channel Details
properties:
email:
type: string
title: Email Address
description: Email address
example: example@freddiemail.com
hashed_email:
type: string
title: Hashed Email Address
description: MD5 hash of the email address
example: 9115d71ba28088047d342e3bcedacd0f
effective_subscription_status:
type: object
description: 'A computation performed by the Mailchimp platform, triggered whenever any of its inputs change. Some inputs are controlled by API users, while others are tracked internally by the platform. Computation is based on: audience opt-in configuration (single vs. double opt-in), marketing consent status, and deliverability status (an internal state for a contact, maintained by Mailchimp for a specific marketing channel instance). This new API field is distinct from how contacts are displayed in the UI. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.'
properties:
value:
type: string
title: Effective Subscription Status
enum:
- subscribed
- unsubscribed
- nonsubscribed
- pending
readOnly: true
marketing_consent:
description: A contact's current consent status for email marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.
type: object
properties:
status:
type: string
title: Marketing Consent Status
enum:
- consented
- denied
- confirmed
- unknown
captured_at:
type: string
format: date-time
title: Captured At
description: The ISO 8601 timestamp when the email marketing consent state was recorded; accepted and returned only when status is `confirmed` or `consented`; defaults to the current time if omitted; ignored if older than an existing stored timestamp (staleness guard).
example: '2024-01-15T10:30:00Z'
source:
type: object
title: Source
description: The source from which the parent's entity was created from.
properties:
name:
type: string
title: Entity source name
description: The name of the entity's source
source:
type: object
title: Source
description: The source from which the parent's entity was created from.
properties:
name:
type: string
title: Entity source name
description: The name of the entity's source
sms_channel:
type: object
title: SMS Channel Details
properties:
sms_phone:
type: string
title: SMS Phone Number
description: SMS Phone Number
example: '+14045550102'
hashed_sms_phone:
type: string
title: Hashed SMS Phone Number
description: SHA256 hash of the SMS phone number
example: 0572084e1f8288816f02cdb7bd930c62400bc8aef510adfaa9eec2b995fa7609
effective_subscription_status:
type: object
description: 'A computation performed by the Mailchimp platform, triggered whenever any of its inputs change. Some inputs are controlled by API users, while others are tracked internally by the platform. Computation is based on: audience opt-in configuration (single vs. double opt-in), marketing consent status, and deliverability status (an internal state for a contact, maintained by Mailchimp for a specific marketing channel instance). This new API field is distinct from how contacts are displayed in the UI. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.'
properties:
value:
type: string
title: Effective Subscription Status
enum:
- subscribed
- unsubscribed
- nonsubscribed
- pending
readOnly: true
marketing_consent:
description: A contact's current consent status for SMS marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.
type: object
properties:
status:
type: string
title: Marketing Consent Status
description: The contact's SMS marketing consent status. Use `confirmed` for double opt-in audiences, `consented` for single opt-in audiences. `denied` is accepted on PATCH/PUT only (not POST) and drives an API-initiated unsubscribe; it cannot be used when creating a new contact.
enum:
- consented
- confirmed
- denied
- unknown
captured_at:
# --- truncated at 32 KB (201 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mailchimp/refs/heads/main/openapi/mailchimp-contacts-api-openapi.yml