feat: add Mailchimp action

[nicosammito]

Summary

Add a Mailchimp action so Hercules flows can manage audiences (lists), subscribers, tags, and campaigns — covering the email-marketing / lifecycle-messaging domain that pairs directly with the e-commerce actions already in centaurus (e.g. a WooCommerce or Shopify order adding/tagging a customer in a Mailchimp audience, or a new HubSpot contact syncing to a newsletter list). Mailchimp is a top marketing integration on both n8n and Zapier.

n8n/Zapier validation: Mailchimp has a first-party node on n8n (add/update subscribers, tags, campaigns) and is one of the most-used marketing apps on Zapier — the classic "new signup → add subscriber → notify" pattern.

Suggested directory

actions/mailchimp-action

Triggers

Mailchimp pushes list/audience events via webhooks registered per audience — this maps onto the existing Rest-based event pattern used by the Shopify action (event classes extend Rest, payload registered as a data type). The webhook type field discriminates subscribe/unsubscribe/profile/cleaned/campaign events.

• MailchimpSubscribed — a member subscribed to a watched audience (setting: audienceId; webhook type=subscribe)
• MailchimpUnsubscribed — a member unsubscribed (type=unsubscribe)
• MailchimpProfileUpdated — a member's profile/merge fields changed (type=profile)
• MailchimpEmailCleaned — an address was cleaned (bounce/complaint) (type=cleaned)
• MailchimpCampaignSent — a campaign finished sending (type=campaign)

Functions

• mailchimpAddOrUpdateMember(audienceId, email, status, mergeFields?): MAILCHIMP_MEMBER — PUT upsert by email hash
• mailchimpGetMember(audienceId, email): MAILCHIMP_MEMBER
• mailchimpUpdateMemberTags(audienceId, email, add?, remove?): BOOLEAN
• mailchimpArchiveMember(audienceId, email): BOOLEAN
• mailchimpDeleteMemberPermanent(audienceId, email): BOOLEAN
• mailchimpListMembers(audienceId, status?, count?, offset?): MAILCHIMP_MEMBER_LIST
• mailchimpCreateCampaign(audienceId, subject, fromName, replyTo, htmlContent): MAILCHIMP_CAMPAIGN
• mailchimpSendCampaign(campaignId): BOOLEAN
• mailchimpGetAudience(audienceId): MAILCHIMP_AUDIENCE

Utils (data-type builders, mirroring GLS create* utils): mailchimpCreateMergeFields(...).

Data types

One class per file in src/data_types/ (zod schema + @Identifier/@Name/@Schema), plus webhook payload schemas per trigger:

• MailchimpMember, MailchimpMemberList, MailchimpAudience, MailchimpCampaign, MailchimpTag
• Webhook payloads: MailchimpSubscribeWebhookPayload, MailchimpUnsubscribeWebhookPayload, MailchimpProfileWebhookPayload, MailchimpCampaignWebhookPayload

Auth / config via ConfigurationDefinition on the Action (like GLS client_id/client_secret):

Identifier	Type	Description
api_key	TEXT	Mailchimp API key (…-usX); the usX suffix selects the server/datacenter
server_prefix	TEXT (optional)	Datacenter prefix (e.g. us21) for the API base host; derivable from the key suffix

Member endpoints require the MD5 hash of the lowercased email as the subscriber id — the action computes this internally so flows pass a plain email. Beyond the shared Hercules vars (HERCULES_AUTH_TOKEN, HERCULES_AQUILA_URL, HERCULES_ACTION_ID, HERCULES_SDK_VERSION) an action-specific MAILCHIMP_API_KEY may back the config default.

Rationale

Email-marketing / lifecycle-messaging domain, not covered by anything in the repo. Not implemented (gls, shopify, shopware, twilio, woocommerce), not on an in-development branch (stripe, github, hubspot/twilio), and not in any open issue/PR (Google Sheets #43, Notion #42, HubSpot #41/#44, S3 #38, SFTP #37, MCP #40, Stripe #35, Discord #34, GitHub #26, SMTP #20, Cron #15, Rest #14, AI #2, WebSocket #16, MQTT #13). Distinct from the planned SMTP (#20) action: SMTP sends individual transactional emails, whereas Mailchimp manages audiences, subscriber tags/segments, and bulk campaigns via a REST API + webhooks. Distinct from HubSpot (#41/#44): HubSpot is CRM/deal-pipeline centric; Mailchimp is audience/newsletter centric and is the go-to for opt-in list management. Complements the e-commerce actions by turning customers into managed marketing contacts.