​
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: 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 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: 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 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: 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"
}

​
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": "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.