New Integration: Mailchimp

Description

Add Mailchimp integration to sync email campaigns, audience data, automation workflows, and campaign analytics into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - OAuth-based API integration
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference

Required Files Structure

integrations/mailchimp/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Mailchimp API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Mailchimp Marketing API Integration

OAuth Setup

• Use OAuth 2.0 Authorization Code flow
• API Version: 3.0 (v2.0 is deprecated)
• Base URL varies by data center: https://<dc>.api.mailchimp.com/3.0/
• Alternative: API Key authentication (simpler but less secure)
• Required scopes determined during OAuth app registration

Key Endpoints

• GET /campaigns - List all campaigns
• GET /campaigns/{campaign_id} - Get campaign details
• GET /campaigns/{campaign_id}/send-checklist - Pre-send checklist
• POST /campaigns/{campaign_id}/actions/send - Send a campaign
• GET /lists - List audiences/lists
• GET /lists/{list_id}/members - List audience members
• GET /automations - List automation workflows
• GET /reports - List campaign reports
• GET /reports/{campaign_id} - Get detailed campaign analytics
• GET /reports/{campaign_id}/open-details - Open tracking details
• GET /reports/{campaign_id}/click-details - Click tracking details

Events to Track

1. Campaigns - Campaign creation, sending, and completion
2. Audience - Subscriber additions, removals, and segment changes
3. Automations - Workflow triggers and completions
4. Reports - Open rates, click rates, bounce rates, and revenue data
5. Templates - Template creation and modifications

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create API utilities in utils.ts for campaigns, audiences, automations, and reports
• Implement sync logic in schedule.ts for polling campaign and audience data
• Convert campaign/audience events to CORE activity format
• Add error handling and rate limiting (10 simultaneous connections max, 120s timeout)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• API v3.0 is the current version; v2.0 is deprecated and no longer supported
• Base URL includes a data center prefix (e.g., us1, us2) that varies per account
• Rate limit: 10 simultaneous connections per account; 429 error on exceeded limit
• API calls have a 120-second timeout
• Supports pagination, filtering, and partial responses
• Webhooks available for real-time event notifications

Resources

• Mailchimp Marketing API Documentation
• API Reference
• Quick Start Guide
• Mailchimp Developer Portal
• Tools and SDKs

Labels

enhancement, integration, new-feature

Start by reading integrations/github/src/index.ts and comparing the existing integrations/github/, integrations/linear/, and integrations/slack/ templates. Then work through the specified integrations/mailchimp/ files and Mailchimp API endpoints. Done means the OAuth flow, campaign and audience sync, activity formatting, error handling, documentation, and integrations/README.md entry are implemented.