Skip to main content

​
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

​
Tools

​
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: [email protected]
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": "[email protected]"
  },
  "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": "[email protected]"
  }
}

​
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": "[email protected]"
  },
  "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: [email protected]
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": "[email protected]",
    "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": "[email protected]",
    "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 Contact to List

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: [email protected]
status: subscribed
first_name: John
last_name: Doe
Response: 
{
  "id": "contact_id",
  "email_address": "[email protected]",
  "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 Contact in List

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: [email protected]
status: subscribed
first_name: John
last_name: Doe
Response: 
{
  "id": "contact_id",
  "email_address": "[email protected]",
  "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"
}

​
Get Contacts from List

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": "[email protected]",
      "status": "subscribed",
      "merge_fields": {
        "FNAME": "John",
        "LNAME": "Doe"
      },
      "timestamp_signup": "2025-01-13T12:00:00+00:00"
    },
    {
      "id": "contact_id_2",
      "email_address": "[email protected]",
      "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.