Mailchimp
Connect the Mailchimp Marketing API and start workflows from audience events and batch completion.
What your agents can do
Agents search the full Mailchimp Marketing API v3 and call it with your connected credentials. They can manage audiences, contacts, segments, campaigns, reports, ecommerce stores, files and batch operations. The index includes all 306 operations in the current official OpenAPI specification. Mailchimp Transactional (Mandrill) is a separate product and is not included.
Authentication
Mailchimp API key
Create a key in your Mailchimp account's Extras > API keys page. In Helios, choose Mailchimp API key and enter the complete value in API key, including the suffix such as -us1. Helios uses that suffix to route requests to your data centre, sends bearer authentication, and tests the connection with GET /ping.
Your own Mailchimp app
Register an OAuth app in Mailchimp. Register the callback URL shown by Helios. Choose Your own Mailchimp app, enter Client ID and Client secret, then authorize the connection. Helios exchanges the code and reads your data centre from Mailchimp's OAuth metadata endpoint.
Mailchimp defines no named OAuth scopes or separate admin scopes. Access follows the authorizing user's permissions. Tokens do not expire and have no refresh token. If access is revoked, authorize the connection again. The weekly setup schedule checks for new audiences; it does not refresh credentials.
Triggers
Helios configures webhooks for every audience returned by your account and a separate batch completion webhook. It checks for new audiences weekly. Audience hooks subscribe to subscriber, admin and API actions. You do not need to create these webhooks manually.
| Event | Meaning | Filters |
|---|---|---|
contact.subscribed | A contact subscribed to email | Audience ID, Contact ID, Email, Email format |
contact.unsubscribed | A contact unsubscribed from email | The subscription filters plus Action, Reason, Campaign ID |
contact.profile_updated | A contact profile changed, including SMS-only contacts in beta | None |
contact.cleaned | An email address was cleaned from an audience | None |
contact.email_updated | A contact email address changed | None |
campaign.finished | An email campaign was sent or cancelled | None |
contact.sms_subscribed | A contact subscribed to SMS (beta) | None |
contact.sms_unsubscribed | A contact unsubscribed from SMS (beta) | None |
contact.sms_phone_updated | A contact SMS phone number changed (beta) | None |
sms_campaign.sent | An SMS campaign was sent (beta) | None |
batch.completed | An API batch operation completed | Batch ID, Status, Error count |
Email accepts case-insensitive patterns such as *@example.com. ID, action, reason, status and error-count filters also accept patterns. Email format offers HTML and plain text. Empty filters accept all values; a selected filter does not match a missing field. Events without filters have no complete payload contract in the current guides, so Helios does not infer field names for them. Opens and clicks are not audience webhook events.
Mailchimp validates webhook URLs with GET and delivers form-encoded POST bodies. Helios registers a generated secret in the callback query and verifies it on deliveries. Keep registered callback URLs private. The current documentation describes optional HMAC signing, but the registration schema does not specify how to activate it. This integration uses the URL secret rather than depending on optional signing. Unsigned timestamps cannot provide authenticated replay protection.
Mailchimp delivers one event per request. A batch completion describes one API batch job, not an array of audience events. Helios derives audience retry IDs from the sorted form fields and batch completion IDs from the batch ID. Identical audience payloads can be deduplicated as one event because Mailchimp supplies no documented delivery ID.
Setup failures and limits
Setup updates existing webhooks at this connection's URL, then removes redundant hooks only when their event and source coverage is retained. If Mailchimp refuses the full audience event set, Helios attempts the flags individually. Failed updates leave the existing hook in place. Events appear as unavailable with a reason only when no remaining authenticated hook delivers them. Delivery in one audience does not guarantee delivery in every audience; review webhook settings in Mailchimp if an audience lacks expected events.
SMS events require the account's SMS features. Free-plan audience webhook entitlement is not clear in the current developer documentation. Mailchimp permits up to 20 batch webhook registrations. Permission, plan and registration-limit errors can prevent setup. Listing failures fail setup or teardown so Helios does not mistake an unreadable subscription for a missing one.
The Marketing API allows ten concurrent connections per user and can return 429 when that limit is exceeded. Audience webhook requests time out after ten seconds and may be retried over 75 minutes. Helios cannot recover events Mailchimp never delivers. See the webhook guide and API limits.
File Manager uploads use base64 data in JSON. Batch results and account exports provide download URLs; agents use curl for signed file transfers. The current schema omits an archive upload shape found in an older campaign-content schema, so the integration indexes the current contract without adding that older input.
Last updated on