Mailchimp Integration

MAILCHIMP_API_KEY=      # From Mailchimp Account → Extras → API Keys
MAILCHIMP_SERVER_PREFIX= # e.g., "us17" (from API key: xxxx-us17)
MAILCHIMP_AUDIENCE_ID=  # Primary audience/list ID (set after first sync)

https://{SERVER_PREFIX}.api.mailchimp.com/3.0/
Authorization: Bearer ***

# Get audience info
GET /lists/{audience_id}

# Add/update member (upsert by email)
POST /lists/{audience_id}/members
{
  "email_address": "partner@example.com",
  "status": "subscribed",
  "merge_fields": {
    "FNAME": "Jane",
    "LNAME": "Smith",
    "COMPANY": "Example Realty",
    "REGION": "Standard",
    "PHONE": "555-555-0199",
    "LEAD_SOURCE": "referral",
    "LAST_CONTACT": "2026-01-10",
    "TAGS": "partner,active"
  },
  "tags": ["partner", "active", "standard_region"]
}

# Batch upsert (for initial import of large contact lists)
POST /lists/{audience_id}/members/batch
{
  "members": [...],
  "update_existing": true
}

# Add tags to member
POST /lists/{audience_id}/members/{subscriber_hash}/tags
{"tags": [{"name": "engaged_30d", "status": "active"}]}

# Archive/unsubscribe
PATCH /lists/{audience_id}/members/{subscriber_hash}
{"status": "unsubscribed"}

# Create segment: "Active partners in Standard Region, contacted last 90 days"
POST /lists/{audience_id}/segments
{
  "name": "Standard Region Partners - Active 90d",
  "options": {
    "match": "all",
    "conditions": [
      {"field": "merge_fields.TAGS", "op": "contains", "value": "partner"},
      {"field": "merge_fields.REGION", "op": "eq", "value": "Standard"},
      {"field": "last_changed", "op": "greater", "value": "2025-10-15"}
    ]
  }
}

# Create regular campaign
POST /campaigns
{
  "type": "regular",
  "recipients": {"list_id": "{audience_id}", "segment_opts": {"saved_segment_id": 123}},
  "settings": {
    "subject_line": "Winter Service Special for Your Listings",
    "preview_text": "Exclusive partner pricing through February",
    "title": "Partner Winter Promo - Jan 2026",
    "from_name": "[BUSINESS_NAME]",
    "reply_to": "owner@yourdomain.com",
    "to_name": "*|FNAME|* *|LNAME|*",
    "folder_id": "campaigns"
  }
}

# Set campaign content (HTML)
PUT /campaigns/{campaign_id}/content
{
  "html": "<html>...",
  "plain_text": "Text version..."
}

# Send test
POST /campaigns/{campaign_id}/actions/test
{"test_emails": ["owner@yourdomain.com"], "send_type": "html"}

# Send campaign
POST /campaigns/{campaign_id}/actions/send

# Welcome series for new partner contacts
POST /automations
{
  "type": "welcome",
  "recipients": {"list_id": "{audience_id}"},
  "settings": {
    "title": "Partner Welcome Series",
    "from_name": "[BUSINESS_NAME]",
    "reply_to": "owner@yourdomain.com",
    "subject_line": "Welcome to [BUSINESS_NAME] Partner Program!",
    "workflow": [
      {"trigger": "subscribed", "delay": "0d", "template": "welcome_email_1"},
      {"delay": "3d", "template": "welcome_email_2_how_it_works"},
      {"delay": "7d", "template": "welcome_email_3_case_study"},
      {"delay": "14d", "template": "welcome_email_4_pricing_guide"}
    ]
  }
}

# Post-job review request (triggered by CRM webhook)
POST /automations
{
  "type": "custom",
  "settings": {
    "title": "Post-Job Review Request",
    "workflow": [
      {"trigger": "api", "event": "job_completed", "template": "review_request_email"}
    ]
  }
}

# Campaign report
GET /reports/{campaign_id}
# Returns: opens, clicks, bounces, unsubscribes, revenue (if ecommerce)

# Member activity
GET /lists/{audience_id}/members/{subscriber_hash}/activity
# Returns: campaign opens/clicks per contact

# Audience growth
GET /lists/{audience_id}/growth-history

# 1. Parse CSV → normalize fields (region, company, phone)
# 2. Batch upsert to Mailchimp (update_existing=true)
# 3. Auto-tag by region: "standard_region", "premium_region", etc.
# 4. Create segments per region
# 5. Report: "Imported 1,847 contacts, 23 duplicates updated"

# 1. Create campaign from template
# 2. Select segment: "All partners, engaged last 60 days"
# 3. Set content (agent drafts, owner approves)
# 4. Send test → owner approves → send
# 5. Log campaign_id to CRM for tracking

# 1. Segment: "No opens/clicks in 90 days, status=subscribed"
# 2. Create "We miss you" campaign with special offer
# 3. Send → track re-engagement → move responders back to active
# 4. Archive non-responders after 30 days

# When new lead enters CRM:
mailchimp.upsert_member(
    email=lead.email,
    merge_fields={
        "FNAME": lead.contact_name.split()[0],
        "COMPANY": lead.company,
        "REGION": detect_region(lead.property_address),
        "LEAD_SOURCE": lead.source,
        "LAST_CONTACT": datetime.now().isoformat()
    },
    tags=["lead", "new"]
)

health = mailchimp.audience_health(audience_id)
# Returns: {total: N, subscribed: N, unsubscribed: N, cleaned: N, 
#           engaged_30d: N, engaged_90d: N, by_region: {...}}

segment = mailchimp.create_segment(
    name="Standard Region Partners - Active",
    conditions=[
        {"field": "TAGS", "op": "contains", "value": "partner"},
        {"field": "REGION", "op": "eq", "value": "Standard"},
        {"field": "last_open", "op": "greater", "value": "90d"}
    ]
)