What can you do with it?
The Mailchimp API allows you to manage your email marketing campaigns and subscriber lists. You can create, update, and send email campaigns, manage audience lists, add and update contacts, search campaigns and lists, and handle all aspects of your email marketing workflow programmatically.
How to use it?
Basic Command Structure
/your-mailchimp-connection [action] [required-parameters] [optional-parameters]
Parameters
Required:
action
- The action to perform (create, update, send, search, get, delete, add)
entity
- The entity type (campaign, list, contact)
id
- Entity ID for specific operations
Optional:
type
- Campaign type (regular, plaintext, rss, variate)
subject_line
- Email subject line
from_name
- Sender name
from_email
- Sender email address
list_id
- List ID for campaigns and contacts
query
- Search query text
Create Campaign
Create a new email campaign in Mailchimp.
Parameters:
type
(required) - Campaign type (regular, plaintext, rss, variate)
list_id
(required) - List ID for recipients
subject_line
(required) - Email subject line
title
(required) - Campaign title
from_name
(required) - Sender name
reply_to
(required) - Reply-to email address
Example:
/your-mailchimp-connection
action: create
entity: campaign
type: regular
list_id: your_list_id
subject_line: Your Subject Here
title: Campaign Title
from_name: Your Name
reply_to: your_email@example.com
Response:
{
"id": "campaign_id",
"type": "regular",
"create_time": "2025-01-13T12:00:00+00:00",
"status": "save",
"settings": {
"subject_line": "Your Subject Here",
"title": "Campaign Title",
"from_name": "Your Name",
"reply_to": "your_email@example.com"
},
"recipients": {
"list_id": "your_list_id"
}
}
Update Campaign
Update settings of an existing campaign in Mailchimp.
Parameters:
campaign_id
(required) - Campaign ID to update
subject_line
(optional) - Updated subject line
title
(optional) - Updated campaign title
from_name
(optional) - Updated sender name
reply_to
(optional) - Updated reply-to email
Example:
/your-mailchimp-connection
action: update
entity: campaign
campaign_id: campaign_id
subject_line: Updated Subject Line
title: Updated Campaign Title
Response:
{
"id": "campaign_id",
"type": "regular",
"create_time": "2025-01-13T12:00:00+00:00",
"status": "save",
"settings": {
"subject_line": "Updated Subject Line",
"title": "Updated Campaign Title",
"from_name": "Your Name",
"reply_to": "your_email@example.com"
}
}
Send Campaign
Send a campaign that has been created and is in draft status.
Parameters:
campaign_id
(required) - Campaign ID to send
Example:
/your-mailchimp-connection
action: send
entity: campaign
campaign_id: campaign_id
Response:
{
"status": 204,
"message": "Campaign sent successfully."
}
Search Campaigns
Search for campaigns in Mailchimp based on specific criteria.
Parameters:
query
(required) - Search query text
limit
(optional) - Number of results to return
Example:
/your-mailchimp-connection
action: search
entity: campaigns
query: Winter Sale
limit: 10
Response:
{
"campaigns": [
{
"id": "campaign_id_1",
"type": "regular",
"create_time": "2025-01-10T12:00:00+00:00",
"status": "sent",
"settings": {
"subject_line": "Winter Sale - 50% Off",
"title": "Winter Sale Campaign"
}
},
{
"id": "campaign_id_2",
"type": "regular",
"create_time": "2025-01-11T12:00:00+00:00",
"status": "save",
"settings": {
"subject_line": "Final Winter Sale",
"title": "Final Winter Sale Campaign"
}
}
]
}
Get Campaign
Retrieve details of a specific campaign using its unique ID.
Parameters:
campaign_id
(required) - Campaign ID to retrieve
Example:
/your-mailchimp-connection
action: get
entity: campaign
campaign_id: campaign_id
Response:
{
"id": "campaign_id",
"type": "regular",
"create_time": "2025-01-13T12:00:00+00:00",
"status": "save",
"settings": {
"subject_line": "Your Subject Here",
"title": "Campaign Title",
"from_name": "Your Name",
"reply_to": "your_email@example.com"
},
"recipients": {
"list_id": "your_list_id"
}
}
Delete Campaign
Remove a campaign from Mailchimp using its unique ID.
Parameters:
campaign_id
(required) - Campaign ID to delete
Example:
/your-mailchimp-connection
action: delete
entity: campaign
campaign_id: campaign_id
Response:
{
"status": 204,
"message": "Campaign deleted successfully."
}
Create List
Create a new list (audience) in Mailchimp.
Parameters:
name
(required) - List name
company
(required) - Company name
address1
(required) - Company address
city
(required) - City
state
(required) - State
zip
(required) - ZIP code
country
(required) - Country
from_name
(required) - Default sender name
from_email
(required) - Default sender email
subject
(required) - Default subject
language
(optional) - Default language
Example:
/your-mailchimp-connection
action: create
entity: list
name: New Audience
company: Your Company
address1: 123 Main St
city: Anytown
state: CA
zip: 12345
country: US
from_name: Your Name
from_email: your_email@example.com
subject: Default Subject
language: en
Response:
{
"id": "list_id",
"name": "New Audience",
"contact": {
"company": "Your Company",
"address1": "123 Main St",
"city": "Anytown",
"state": "CA",
"zip": "12345",
"country": "US"
},
"campaign_defaults": {
"from_name": "Your Name",
"from_email": "your_email@example.com",
"subject": "Default Subject",
"language": "en"
}
}
Get List
Retrieve details of a specific list (audience) using its unique ID.
Parameters:
list_id
(required) - List ID to retrieve
Example:
/your-mailchimp-connection
action: get
entity: list
list_id: list_id
Response:
{
"id": "list_id",
"name": "Existing Audience",
"contact": {
"company": "Your Company",
"address1": "123 Main St",
"city": "Anytown",
"state": "CA",
"zip": "12345",
"country": "US"
},
"campaign_defaults": {
"from_name": "Your Name",
"from_email": "your_email@example.com",
"subject": "Default Subject",
"language": "en"
}
}
Search Lists
Search for lists (audiences) in Mailchimp based on specific criteria.
Parameters:
name
(optional) - Search by list name
fields
(optional) - Fields to return
Example:
/your-mailchimp-connection
action: search
entity: lists
name: Newsletter
fields: lists.name,lists.id
Response:
{
"lists": [
{
"id": "list_id_1",
"name": "Newsletter Audience"
},
{
"id": "list_id_2",
"name": "Promotions Audience"
}
]
}
Add a contact to a specific list (audience) in Mailchimp.
Parameters:
list_id
(required) - List ID to add contact to
email_address
(required) - Contact email address
status
(required) - Subscription status (subscribed, unsubscribed, cleaned, pending)
first_name
(optional) - Contact first name
last_name
(optional) - Contact last name
Example:
/your-mailchimp-connection
action: add
entity: contact
list_id: list_id
email_address: john.doe@example.com
status: subscribed
first_name: John
last_name: Doe
Response:
{
"id": "contact_id",
"email_address": "john.doe@example.com",
"status": "subscribed",
"merge_fields": {
"FNAME": "John",
"LNAME": "Doe"
},
"timestamp_signup": "2025-01-13T12:00:00+00:00",
"timestamp_opt": "2025-01-13T12:00:00+00:00"
}
Update details of an existing contact in a specific list (audience).
Parameters:
list_id
(required) - List ID containing the contact
subscriber_hash
(required) - Subscriber hash or email address
email_address
(optional) - Updated email address
status
(optional) - Updated subscription status
first_name
(optional) - Updated first name
last_name
(optional) - Updated last name
Example:
/your-mailchimp-connection
action: update
entity: contact
list_id: list_id
subscriber_hash: 123abc456def789ghi
email_address: john.new@example.com
status: subscribed
first_name: John
last_name: Doe
Response:
{
"id": "contact_id",
"email_address": "john.new@example.com",
"status": "subscribed",
"merge_fields": {
"FNAME": "John",
"LNAME": "Doe"
},
"timestamp_signup": "2025-01-13T12:00:00+00:00",
"timestamp_opt": "2025-01-13T12:00:00+00:00"
}
Retrieve all contacts in a specific list (audience) in Mailchimp.
Parameters:
list_id
(required) - List ID to retrieve contacts from
status
(optional) - Filter by subscription status
limit
(optional) - Number of contacts to return
Example:
/your-mailchimp-connection
action: get
entity: contacts
list_id: list_id
status: subscribed
limit: 100
Response:
{
"members": [
{
"id": "contact_id_1",
"email_address": "john.doe@example.com",
"status": "subscribed",
"merge_fields": {
"FNAME": "John",
"LNAME": "Doe"
},
"timestamp_signup": "2025-01-13T12:00:00+00:00"
},
{
"id": "contact_id_2",
"email_address": "jane.doe@example.com",
"status": "unsubscribed",
"merge_fields": {
"FNAME": "Jane",
"LNAME": "Doe"
},
"timestamp_signup": "2025-01-12T12:00:00+00:00"
}
]
}
Notes
Campaign types include regular, plaintext, rss, and variate. Contact status can be subscribed, unsubscribed, cleaned, or pending. Lists require complete contact information including company address. Subscriber hash is used for updating contacts and can be the MD5 hash of the email address. Uses Paragon proxy connection. Campaign content and templates are managed separately from campaign settings. Merge fields like FNAME and LNAME are used for personalization.