Mailchimp API Essential Guide

What type of API does Mailchimp provide?

Mailchimp primarily uses a REST API.

REST API

• The Mailchimp Marketing API largely follows RESTful API conventions, providing resources and actions at specified URIs.

• It accepts standard HTTP methods like GET, POST, PATCH, PUT, and DELETE for interacting with resources.

Key Points

• Mailchimp's API is designed as a RESTful API, not SOAP or GraphQL.

• It uses typical REST conventions like HTTP methods, resource URIs, and JSON data format.

• The API documentation refers to it as the "Mailchimp Marketing API".

Does the Mailchimp API have webhooks?

Yes, the official Mailchimp API has webhooks. Mailchimp offers webhooks for both their Transactional API and Marketing API.

Event Types

Transactional API event types:

• Message events: Sent, Opened, Clicked, Delivered, Delayed, Marked as Spam, Bounced, Recipient Unsubscribes, Rejected
• Sync events: Rejection Denylist Changes, Rejection Allowlist Changes
• Inbound messages

Marketing API event types:

• Subscribes
• Unsubscribes
• Campaign sending
• Email address changes
• Profile updates

Setting Up Webhooks

You can set up webhooks through:

1. The Mailchimp web application
2. Using the API

Key Considerations

• Webhooks are triggered by specific actions in your Mailchimp account.
• They send HTTP POST requests to a specified URL with event details.
• You need to provide a callback URL that accepts HTTP POST requests.
• Mailchimp recommends using HTTPS URLs for security.
• You can test webhooks before implementing them in production.

Best Practices

• Use webhooks to keep your application in sync with Mailchimp data in real-time.
• Implement proper error handling and retries in your webhook handler.
• Authenticate incoming webhook requests to ensure they're from Mailchimp.

Rate Limits and other limitations

Here are the key points about the API rate limits for the Mailchimp API:

Simultaneous Connection Limit

• The Mailchimp Marketing API has a limit of 10 simultaneous connections per user.
• Requests exceeding this limit will receive a 429 (Too Many Requests) error response.
• This limit is per user, not per API key or client.

Request Timeout

• The Marketing API has a 120-second timeout on API calls.
• Long-running requests that may exceed this timeout should be sent to the Batch endpoint instead.

Throttling

• At exceptionally high volumes, you may receive HTTP 429 or 403 errors without a JSON body.
• It's recommended to cache frequently accessed values that don't change often to avoid hitting throttling limits.

Message Search Rate Limit

• There is a limit of 20 searches per minute for the message search endpoint.
• Exceeding this limit will result in a 429 Too Many Requests response.
• You can retry the request 60 seconds after sending the first of the original 20 requests.

Best Practices

• Use the Batch endpoint for long-running requests or high-volume operations to work around the simultaneous connection limit.
• Monitor responses for 429 codes and adjust your request system if necessary.
• Cache frequently accessed data in your application to reduce API calls.
• Consider using pagination and partial response capabilities to optimize requests.

Key Considerations

• API access is tied to the user who created the API key or authorized the OAuth2 app.
• API access is limited by the user's role, which can change over time.
• It's recommended to use an admin user when possible for creating API keys or authorizing apps.

By understanding and adhering to these rate limits, you can ensure efficient and compliant use of the Mailchimp API in your applications.

Latest API Version

The most recent version of the Mailchimp API is version 3.0.

Key points to consider:

• The Mailchimp Marketing API is currently on version 3.0.
• The previous version 2.0 has been deprecated and is no longer supported.
• Version 1.0 of the Export API is still supported for some account export functionality.
• Earlier versions (1.1, 1.2, and 1.3) are no longer available.

Additional information:

• Mailchimp recommends migrating to version 3.0 since version 2.0 is not regularly tested or maintained.
• The Marketing API provides programmatic access to Mailchimp data and functionality, allowing developers to build custom features.
• The API has a 120-second timeout on API calls.
• Mailchimp retired API Export 1.0 and API 2.0 on June 1, 2023.

Best practices:

• Use pagination and partial response capabilities to optimize requests and avoid timeouts.
• Consider using the Batch endpoint for long-running requests if you're regularly experiencing timeout issues.
• Stay updated with the latest API version to ensure access to the most recent features and improvements.
• Keep an eye on the Release Notes for any upcoming changes or deprecations that may affect your integration.

How to get a Mailchimp developer account and API Keys?

To get a developer account for Mailchimp and create an API integration:

1. Create a Mailchimp account if you don't have one.

2. Generate an API key:

   • Log in to your Mailchimp account.
   • Navigate to the API Keys section.
   • Click "Create New Key" and give it a descriptive name.
   • Copy the generated key immediately and store it securely.

3. Protect your API key:

   • API keys grant full access to your account.
   • Give each integration its own API key.
   • Don't expose the key publicly.
   • Avoid client-side implementation or including keys in mobile apps.

4. Consider using OAuth 2 authentication for integrations accessing Mailchimp on behalf of other users.

5. Install the official Mailchimp client library for your preferred programming language.

6. Familiarize yourself with the Marketing API documentation and API Reference.

7. Make your first API call to test your setup.

8. Learn how to create your first audience and add contacts using the API.

9. Explore other API functionalities like managing campaigns and syncing email activity.

For Mailchimp Marketplace integrations:

1. Meet the requirements for the Integration Partner Program.
2. Use OAuth 2 for authentication.
3. Implement at least three core Mailchimp functionality features.
4. Apply to join the Integration Partner Program when ready.

What can you do with the Mailchimp API?

Based on the Mailchimp Marketing API documentation, here are the key data models you can interact with and what is possible for each:

Lists/Audiences

• Create and manage mailing lists/audiences
• Add, update, and remove subscribers
• Manage list segments and groups
• Handle merge fields and interest categories

Campaigns

• Create and send email campaigns
• Manage campaign content and settings
• Schedule and test campaigns
• View campaign reports and analytics

Automations

• Create and manage automation workflows
• Add, update, and remove emails in workflows
• Start, pause, and archive automations
• View automation reports

Templates

• Create and manage email templates
• Organize templates into folders

Reports

• View campaign and automation reports
• Access click, open, and other engagement metrics
• View e-commerce data related to campaigns

E-commerce Stores

• Connect and manage e-commerce store integrations
• Sync product data and purchase activity
• Create product recommendations

Landing Pages

• Create and publish landing pages
• Manage landing page content and settings
• View landing page performance metrics

File Manager

• Upload and manage images and files for use in campaigns

Conversations (Deprecated)

• View subscriber replies to campaigns (now replaced by Inbox)

Authorized Apps

• Manage API keys and authorized applications

Account Exports

• Request and retrieve exports of account data

Batch Operations

• Perform bulk operations on multiple API endpoints

This covers the main data models, but the API also includes additional resources for managing things like Facebook ads, connected sites, verified domains, and more. Each model allows for various CRUD (Create, Read, Update, Delete) operations as appropriate for that resource type.