Mailchimp Audiences API
The audiences API from Mailchimp — 2 operation(s) for audiences.
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-audiences-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 Audiences 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: audiences
paths:
/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:
type: string
format: date-time
title: Captured At
description: The timestamp when SMS marketing consent was captured (ISO 8601). Only accepted and returned when status is `confirmed`. The timestamp of the consent state change being recorded. Defaults to the current time if not provided. If the contact already has a newer consent timestamp on record, the supplied value is ignored (staleness guard); to update the consent timestamp supply a value equal to or newer than the stored one.
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
merge_fields:
type: object
title: Merge Fields
description: A dictionary of merge fields where the keys are the merge tags. See the [Merge Fields documentation](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for more about the structure.
additionalProperties:
description: This object's keys are merge tags (like FNAME). It's values are the values to be added to the merge field.
tags:
type: array
title: Tags
description: The tags assigned to this contact.
items:
type: string
title: Tag Name
description: The name of the tag
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
created_at:
type: string
format: date-time
title: Created At
description: The date that the contact was created.
readOnly: true
last_updated_at:
type: string
format: date-time
title: Updated At
description: The date that the contact was last updated.
readOnly: true
next_cursor:
type: string
title: Next Cursor
description: A cursor pointing to the last item on this page of the collection. Paginate through a collection of records by setting the `cursor` parameter on a subsequent request to this value.
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
application/problem+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:
type: string
format: date-time
title: Captured At
description: The timestamp when SMS marketing consent was captured (ISO 8601). Only accepted and returned when status is `confirmed`. The timestamp of the consent state change being recorded. Defaults to the current time if not provided. If the contact already has a newer consent timestamp on record, the supplied value is ignored (staleness guard); to update the consent timestamp supply a value equal to or newer than the stored one.
example: '2024-01-15T10:30:00Z'
# --- truncated at 32 KB (174 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mailchimp/refs/heads/main/openapi/mailchimp-audiences-api-openapi.yml