Mailchimp Integration

🌐 Overview

Mailchimp integration providing access to email marketing lists and contact management through OAuth 2.0 authentication. Supports list retrieval, member export, and persistent access token storage.

Provider: Mailchimp (https://mailchimp.com)
API Version: v3
Integration Type: OAuth 2.0 with persistent access tokens

📚 Documentation Structure

This integration is organized into the following sections:

1. Authentication - OAuth 2.0 flow and token management
2. Contact Lists - List management and member export

🔧 Features

• ✅ OAuth 2.0: Secure authentication with persistent access tokens
• ✅ List Management: Retrieve all email lists for an account
• ✅ Contact Export: Export all list members with pagination
• ✅ Data Center Support: Automatic datacenter detection and routing
• ✅ Sub-account Support: Works with DashClicks sub-accounts
• ✅ No Token Expiry: Mailchimp access tokens never expire

📊 Architecture

Frontend Request
       ↓
  OAuth Flow
       ↓
Datacenter Detection
       ↓
Token Storage (MongoDB)
       ↓
Mailchimp API v3
       ↓
Lists & Member Data

🗄️ MongoDB Collections

📚 Detailed Schema: See Database Collections Documentation

integrations.mailchimp.key

Purpose: Store OAuth 2.0 tokens and datacenter metadata

Key Fields:

• token (Object) - Token information
  • access_token (String) - OAuth access token (never expires)
  • metadata (Object) - Account metadata
    • dc (String) - Mailchimp datacenter (e.g., "us8")
• account_id (String) - DashClicks account ID
• owner (String) - DashClicks user ID
• token_invalidated (Boolean) - Token invalidation flag

Indexes:

• { account_id: 1, owner: 1 } (unique) - Primary lookup

Schema: Flexible schema (strict: false) for dynamic fields

📁 Directory Structure

Source Code Location:

external/Integrations/Mailchimp/
├── Controller/
│   ├── authController/
│   │   └── index.js      # OAuth handlers
│   └── contactController/
│       └── index.js      # List/contact operations
├── Providers/
│   ├── authProvider/
│   │   └── index.js      # OAuth API calls
│   └── contactProvider/
│       └── index.js      # List/contact API calls
├── Model/
│   └── authModel/
│       └── index.js      # Database operations
├── Routes/
│   ├── authRoutes/       # Auth endpoints
│   └── exportRoutes/     # Export endpoints
└── index.js              # Route registration

Shared Models Used:

• shared/models/mailchimp-key.js

🚀 Quick Start

1. Configure Environment Variables

# OAuth Configuration
MAILCHIMP_CLIENT_ID=your_client_id
MAILCHIMP_CLIENT_SECRET=your_client_secret
MAILCHIMP_REDIRECT_URI=https://api.dashclicks.com/v1/integrations/mailchimp/callback

# OAuth URLs
MAILCHIMP_AUTHORIZATION_URL=https://login.mailchimp.com/oauth2/authorize
MAILCHIMP_TOKEN_URL=https://login.mailchimp.com/oauth2/token
MAILCHIMP_DATACENTER_URL=https://login.mailchimp.com/oauth2/metadata
MAILCHIMP_RESPONSE_TYPE=code
MAILCHIMP_GRANT_TYPE=authorization_code

# API Endpoints
MAILCHIMP_LIST=/api/3.0/lists

2. Initiate OAuth Flow

GET /v1/integrations/mailchimp/auth/login?forward_url=https://app.dashclicks.com/integrations
Authorization: Bearer {jwt_token}

3. Export All Contacts

GET /v1/integrations/mailchimp/export
Authorization: Bearer {jwt_token}

4. Export with Pagination

GET /v1/integrations/mailchimp/export?count=100&offset=0
Authorization: Bearer {jwt_token}

📖 API Endpoints Summary

Method	Endpoint	Description
GET	/auth/login	Initiate OAuth 2.0 flow
GET	/callback	Handle OAuth callback
DELETE	/auth	Delete stored access token
GET	/export	Export all contacts from all lists
GET	/export/:id	Export contacts from specific list

🔑 Authentication Flow

OAuth Scopes

Mailchimp uses a simple OAuth 2.0 flow without explicit scopes:

// Scopes are managed through app permissions in Mailchimp dashboard
// Not specified in authorization URL

Token Characteristics

• Never Expires: Mailchimp access tokens have no expiration
• Revocation: Tokens remain valid until manually revoked
• Single Connection: One active connection per user/account combination

🌍 Datacenter Detection

Mailchimp accounts are region-specific. The integration automatically detects and stores the datacenter:

// Example datacenters
'us1'; // United States (East)
'us8'; // United States (Central)
'us19'; // United States (West)

API calls use datacenter-specific URLs:

https://{dc}.api.mailchimp.com/3.0/...

📊 Data Export Process

The integration handles large-scale exports with automatic pagination:

1. Fetch All Lists: Get list IDs and member counts
2. Paginate Lists: Handle lists with 1000+ members
3. Extract Members: Fetch email addresses and merge fields
4. Aggregate Data: Combine all members into single response

Maximum per request: 1000 members
Automatic handling: Multi-list, multi-page exports

⚙️ Query Parameters

Export Endpoints

Parameter	Type	Description	Default	Max
count	Integer	Records per request	10	1000
offset	Integer	Skip N records	0	-
fields	Array	Comma-separated fields to return	All	-
exclude_fields	Array	Fields to exclude	None	-

🔗 Related Documentation

• Mailchimp API Documentation
• OAuth 2.0 Reference
• Lists API
• List Members API

⚠️ Important Notes

• 🔒 Persistent Tokens: Access tokens never expire
• 🌍 Datacenter Routing: All requests routed to correct datacenter
• 📊 Auto Pagination: Handles large lists automatically
• 👤 Single Connection: One token per user/account pair
• ⚡ Performance: Large exports may take several seconds

🎯 Common Use Cases

Export All Contacts

GET /v1/integrations/mailchimp/export

Returns all members from all lists with email and merge fields.

Paginated Export

GET /v1/integrations/mailchimp/export?count=500&offset=1000

Fetch 500 contacts starting from position 1000.

Specific Fields Only

GET /v1/integrations/mailchimp/export?fields=members.email_address,members.merge_fields.FNAME

Return only email addresses and first names.

🔧 Setup Instructions

Create Mailchimp App

1. Visit https://us8.admin.mailchimp.com/
2. Click Profile → Extras → Registered Apps
3. Create new app or select existing
4. Copy Client ID, Client Secret, and Redirect URL
5. Add to .env file

Configure Permissions

Ensure app has these permissions:

• Read-only access to lists
• Read-only access to list members

🐛 Troubleshooting

"Access Token Not Found"

Token hasn't been stored yet. Initiate OAuth flow.

"Only one active connection allowed"

Existing token found. Delete old token first or use existing connection.

Incorrect Datacenter

Token metadata corrupted. Re-authenticate to refresh datacenter info.

📈 Performance Considerations

• Large Lists: Lists with 10,000+ members may take 30+ seconds
• Rate Limits: Mailchimp limits to 10 requests/second
• Batch Processing: Consider implementing queue-based exports for very large accounts
• Caching: Cache list data for frequently accessed accounts