MailChimp Integratie - Domein Overzicht¶

Laatste update: 2025-12-15 Status: Living document Parent: [[00-PROJECT-INDEX]]

[[#Integratie Overzicht]] - API, sync, features
[[#Custom Module]] - vg_mailchimp_subscribe
[[#Data Mapping]] - Profile velden naar MailChimp
[[#Configuration]] - Settings & deployment

Overzicht¶

Automatische MailChimp nieuwsbrief synchronisatie bij openbaar profile saves.

Stack: - MailChimp API v3.0 - Custom module: vg_mailchimp_subscribe - Event subscriber: profile save - Library: thinkshout/mailchimp-api-php

Status: Live & operationeel

Integratie Overzicht¶

Features¶

Auto-subscribe: - Trigger: Openbaar profile save - Method: PUT /lists/{list_id}/members/{hash} - Upsert: Create of update member - Status: subscribed (geen double opt-in)

Data Sync: - Email: from user account - FNAME: from openbaar profile - LNAME: from openbaar profile - Merge fields: configurabel via UI

Settings UI: - Path: /admin/config/services/vg-mailchimp-subscribe - Config: API key, List ID, merge field mapping - Status: Live configured

API Details¶

Endpoint:

PUT https://us21.api.mailchimp.com/3.0/lists/{list_id}/members/{subscriber_hash}

Subscriber Hash:

$subscriber_hash = md5(strtolower($email));

Request Body:

{
  "email_address": "user@example.com",
  "status": "subscribed",
  "merge_fields": {
    "FNAME": "John",
    "LNAME": "Doe"
  }
}

Upgrade: Van 2.x naar 3.x API (2025-11) - Old: mailchimp.lists service - New: mailchimp.api service + direct HTTP calls

Custom Module¶

vg_mailchimp_subscribe¶

Locatie: /var/www/sites/dev.voedingsgeneeskunde/web/modules/custom/vg_mailchimp_subscribe/

Composer Dependency:

{
  "require": {
    "drewm/mailchimp-api": "^2.5"
  }
}

(Note: Package name changed, maar nog steeds v3.0 API compatible)

Components:

EventSubscriber: - Class: ProfileSaveSubscriber - Event: profile.presave of entity.insert/update - Logic: 1. Check if profile type = openbaar 2. Load user email 3. Extract FNAME, LNAME from profile 4. Call MailChimp API (PUT members) - File: src/EventSubscriber/ProfileSaveSubscriber.php

Settings Form: - Route: /admin/config/services/vg-mailchimp-subscribe - Config: vg_mailchimp_subscribe.settings - Fields: - API key (text, required) - List ID (text, required) - Merge field mapping (textarea, JSON/YAML) - File: src/Form/SettingsForm.php

Service: - Service ID: vg_mailchimp_subscribe.subscriber - Wrapper voor MailChimp API calls - Error handling & logging

Data Mapping¶

Profile Fields -> MailChimp¶

Drupal Field	MailChimp Field	Source	Required
user.mail	email_address	User account	Yes
field_profiel_voornaam*	FNAME	openbaar profile	No
field_profiel_achternaam*	LNAME	openbaar profile	No

*Note: Exacte veldnamen verifiëren in code

Future Mappings¶

Potential additions: - field_beroep -> BEROEP (custom merge field) - field_profiel_website -> WEBSITE - user.created -> SIGNUPDATE - Preferences/interests

Configuration¶

Development Setup¶

API Key: Test/sandbox key List ID: Dev test list Status: Enabled

Live Setup¶

API Key: Production key (configured) List ID: Main newsletter list Status: Enabled & syncing

Deployment: - Config export via ddrush cex - API keys in settings.php of secrets management - Module enabled on live

Troubleshooting¶

Common Issues¶

Issue: Sync not working - Check: Module enabled? - Check: API key valid? - Check: List ID correct? - Logs: Drupal watchdog mailchimp

Issue: Wrong data synced - Check: Field mapping in settings - Check: Profile type = openbaar? - Check: User has email?

Issue: API rate limits - MailChimp limits: vary per account - Implement: Queue for bulk operations - Current: Direct sync (low volume OK)

Recent Sessions¶

[[20251201-live-sync-profiles-mailchimp]] - Live deployment (2025-12-01)
[[20251119-mailchimp-eca-openbaar-profiel]] - ECA integration (2025-11-19)
[[20251113-users-profielen-mailchimp]] - Initial setup (2025-11-13)

Cross-Domain: - [[USER-EXPERIENCE-overzicht]] - Profile system - [[00-PROJECT-INDEX]] - Master index

Key Documents: - [[20251201-live-sync-profiles-mailchimp]] - Most recent implementation - [[20251120-nieuwsbrief-user-profielen-pathauto]] - Profile & pathauto

Future Enhancements¶

Planned: - [ ] Double opt-in option (configureerbaar) - [ ] Unsubscribe handling - [ ] Webhook integration (MailChimp -> Drupal) - [ ] Batch sync voor bestaande users - [ ] Interest groups/tags support

Under Consideration: - Campaign integration (send campaigns from Drupal) - Analytics dashboard - A/B testing integration

Document eigenaar: Team Voedingsgeneeskunde Laatste update: 2025-12-15 Versie: 1.0

Voor AI: MailChimp integratie domein. Zie [[20251201-live-sync-profiles-mailchimp]] voor live deployment details. Module: vg_mailchimp_subscribe, API v3.0, auto-sync via profile save event.