Contact Lists Management

📊 Contact Export API

Mailchimp integration provides contact export functionality with automatic handling of large lists and multi-list aggregation.

📋 API Endpoints

Method	Endpoint	Description	Auth Required
GET	/v1/integrations/mailchimp/export	Export all contacts from all lists	✅ JWT
GET	/v1/integrations/mailchimp/export/:id	Export contacts from specific list	✅ JWT

🔧 Query Parameters

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

📖 Export All Contacts

Endpoint: GET /export

Request:

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

Response:

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "id": "abc123def456",
      "email_address": "john.doe@example.com",
      "merge_fields": {
        "FNAME": "John",
        "LNAME": "Doe",
        "ADDRESS": "123 Main St",
        "PHONE": "+1234567890"
      }
    },
    {
      "id": "def456ghi789",
      "email_address": "jane.smith@example.com",
      "merge_fields": {
        "FNAME": "Jane",
        "LNAME": "Smith",
        "ADDRESS": "456 Oak Ave",
        "PHONE": "+0987654321"
      }
    }
  ]
}

With Pagination

Request:

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

Returns 100 contacts starting from position 500.

With Field Selection

Request:

GET /v1/integrations/mailchimp/export?fields=members.email_address,members.merge_fields.FNAME
Authorization: Bearer {jwt_token}

Response:

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "email_address": "john.doe@example.com",
      "merge_fields": {
        "FNAME": "John"
      }
    }
  ]
}

📖 Export Specific List

Endpoint: GET /export/:id

Path Parameters:

• id (required) - Mailchimp list ID

Request:

GET /v1/integrations/mailchimp/export/abc123?count=50
Authorization: Bearer {jwt_token}

Response: Same format as export all, but limited to specified list.

🔄 Export Process

The integration implements intelligent pagination and list aggregation:

Step 1: Fetch All Lists

// Get total list count
GET https://{dc}.api.mailchimp.com/3.0/lists?fields=total_items

Response:

{
  "total_items": 25
}

Step 2: Retrieve List IDs

Automatically handles pagination for 1000+ lists:

// Get list IDs with member counts
GET https://{dc}.api.mailchimp.com/3.0/lists
  ?fields=lists.id,lists.stats.member_count
  &count=1000
  &offset=0

Response:

{
  "lists": [
    {
      "id": "abc123",
      "stats": {
        "member_count": 2500
      }
    },
    {
      "id": "def456",
      "stats": {
        "member_count": 750
      }
    }
  ]
}

Step 3: Fetch Members from Each List

For each list, fetch members with automatic pagination:

// Get members (max 1000 per request)
GET https://{dc}.api.mailchimp.com/3.0/lists/{list_id}/members
  ?fields=members.email_address,members.id,members.merge_fields
  &count=1000
  &offset=0

Response:

{
  "members": [
    {
      "id": "abc123def456",
      "email_address": "user@example.com",
      "merge_fields": {
        "FNAME": "John",
        "LNAME": "Doe"
      }
    }
  ]
}

Step 4: Aggregate Results

All members from all lists are aggregated into single response array.

⚡ Performance & Pagination

Automatic Pagination Logic

For Lists:

if (total_items <= 1000) {
  // Single request
  fetch(count: total_items, offset: 0)
} else {
  // Multiple requests
  while (remaining > 0) {
    fetch(count: 1000, offset: current_offset)
    current_offset += 1000
  }
}

For List Members:

if (member_count <= 1000) {
  // Single request
  fetch(list_id, count: member_count, offset: 0)
} else {
  // Multiple requests
  while (remaining > 0) {
    fetch(list_id, count: 1000, offset: current_offset)
    current_offset += 1000
  }
}

Performance Characteristics

Scenario	Requests	Approximate Time
1 list, 500 members	2	< 1 second
3 lists, 2000 members each	8	2-3 seconds
10 lists, 5000 members each	60	15-20 seconds
50 lists, 10000 members each	550+	2-3 minutes

Rate Limiting

• Mailchimp Limit: 10 requests/second
• Implementation: Sequential requests (no concurrency)
• Recommendation: Use queue-based processing for large exports

🔧 Provider Methods

getAllLists()

Purpose: Fetch all contacts from all lists with automatic pagination

Implementation:

1. Get total list count
2. Paginate through all lists (1000 per request)
3. For each list, paginate through members (1000 per request)
4. Aggregate all members into single array

Returns: Array of member objects

getListByID(id, token, queryParams)

Purpose: Fetch members from specific list

Parameters:

• id - List ID
• token - Token object with access_token and metadata.dc
• queryParams - Pagination parameters (count, offset)

Returns: Member data with pagination info

reteriveAllListIDs(token, queryParams)

Purpose: Fetch list IDs and member counts

Parameters:

• token - Token object
• queryParams - Pagination parameters

Returns: Array of list objects with IDs and member counts

📊 Response Data Structure

Member Object

{
  id: "abc123def456",              // Mailchimp member ID
  email_address: "user@example.com", // Email address
  merge_fields: {                   // Custom fields
    FNAME: "John",
    LNAME: "Doe",
    ADDRESS: "123 Main St",
    PHONE: "+1234567890",
    BIRTHDAY: "01/15",
    // ... additional custom fields
  }
}

Merge Fields

Common merge fields (customizable per list):

• FNAME - First name
• LNAME - Last name
• ADDRESS - Street address
• PHONE - Phone number
• BIRTHDAY - Birthday (MM/DD format)
• COMPANY - Company name

🎯 Common Use Cases

Export All Contacts

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

Use when syncing entire Mailchimp account to DashClicks.

Incremental Export

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

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

Use for progressive loading or processing in chunks.

Email-Only Export

GET /v1/integrations/mailchimp/export?fields=members.email_address
Authorization: Bearer {jwt_token}

Use when only email addresses are needed.

Exclude Large Fields

GET /v1/integrations/mailchimp/export?exclude_fields=members.merge_fields.ADDRESS
Authorization: Bearer {jwt_token}

Use to reduce response size when certain fields aren't needed.

⚠️ Error Handling

Error	Status	Response
Token not found	404	{ success: false, errno: 400, message: "Api Token Not Found" }
Invalid list ID	404	Error from Mailchimp API
Rate limit exceeded	429	Error from Mailchimp API
Invalid query params	400	Error from Mailchimp API

📝 Important Notes

• 🔄 Automatic Pagination: No manual pagination needed for large exports
• 📊 Multi-List Aggregation: All lists exported in single response
• ⚡ Performance: Large accounts may take several minutes
• 🎯 Field Selection: Use fields parameter to reduce response size
• 🌍 Datacenter Routing: Uses correct datacenter from token metadata
• 🔒 Token Required: Must authenticate before exporting

🚀 Optimization Tips

For Large Exports

1. Use Field Selection: Only request needed fields
2. Implement Pagination: Don't fetch all at once
3. Queue Processing: Use background jobs for 10,000+ contacts
4. Cache Results: Store exports for frequently accessed accounts
5. Monitor Performance: Track response times and adjust strategies

Example Queue Implementation

// Queue job for large export
{
  type: 'mailchimp-export',
  account_id: '12345',
  user_id: 'user_abc',
  batch_size: 1000,
  fields: 'members.email_address,members.merge_fields.FNAME'
}

🔗 Related Documentation

• Authentication
• Mailchimp Lists API
• Mailchimp List Members API
• Mailchimp Rate Limits