Mailchimp Email Marketing Integration

The Mailchimp integration allows your organisation to sync employee and vendor contacts into Mailchimp audiences, create targeted contact segments, and monitor campaign performance — all from within the platform dashboard. Email preferences are managed per-contact with full GDPR compliance.

Prerequisites

A Mailchimp account with at least one Audience (list) created.
A Mailchimp API key. Format: <key>-<datacenter> e.g. abc123def456-us6.
- Generate one in Mailchimp → Account → Extras → API keys.
No global environment variable is required. Each organisation provides its own API key through the dashboard UI.

Connecting Mailchimp

Navigate to Dashboard → Integrations → Mailchimp.
In the Connect Mailchimp panel, paste your API key into the field.
Click Connect Mailchimp.

The platform validates the key format (must end in -usN) and immediately verifies it against the Mailchimp API. On success, the connection panel displays your Mailchimp account name, detected data centre, and sync status.

Note: API keys are stored encrypted (base64-encoded JSON) on a per-organisation basis. No key is shared across organisations.

Disconnecting

Click Disconnect in the connection panel. The connection is soft-deleted; all previously synced segment and campaign data is retained in the platform.

Contact Segments

Segments are logical groups of contacts mapped to a Mailchimp audience list. When a segment syncs, the platform pushes matching contacts to the corresponding Mailchimp list using the batch subscribe API (up to 500 contacts per call).

Creating a Segment

Open the Segments tab on the Mailchimp dashboard page.
Click New Segment.
Fill in:
- Name — a human-readable label (e.g. All Active Employees).
- Description — optional context.
- Segment type — employee, vendor, or mixed.
- Mailchimp Audience — select from the audiences fetched from your connected account.
Optionally apply filter criteria:
- Department
- Location
- Employment type
- Employment status
Click Create.

Syncing a Segment

Manual sync: Click the sync icon next to a segment in the list. An event-driven Inngest job (mailchimp-segment-sync) is triggered immediately.
Automatic sync: A scheduled job (mailchimp-scheduled-sync) runs every day at 05:00 UTC and fans out to all segments across all connected organisations.

Segment Statuses

Status	Meaning
`pending`	Created but not yet synced
`syncing`	Sync job currently running
`synced`	Last sync completed successfully
`error`	Last sync encountered an error

Campaign Tracking

The platform imports Mailchimp campaign metadata and tracks key performance metrics.

Importing a Campaign

Use the Campaigns tab to import a campaign by its Mailchimp campaign ID (trackCampaign). Once imported, the following stats are tracked:

Open rate
Click rate
Campaign status (draft, scheduled, sending, sent, paused, cancelled)

Automatic Stats Refresh

A background job (mailchimp-campaign-stats-refresh) runs every 6 hours and refreshes stats for all campaigns that are not yet in a terminal state (sent or cancelled).

GDPR & Email Preferences

The integration includes per-contact opt-in/out management to support GDPR requirements.

How Consent Is Tracked

Every preference change records:

consentGivenAt — timestamp when the contact opted in.
consentWithdrawnAt — timestamp when the contact opted out.
Consent source — the channel or mechanism through which the preference was set.

Updating Opt Status

Use mailchimp.preferences.updateOptStatus (tRPC) to record an opt-in or opt-out for a given contact. All changes are written to the email_preferences table and emitted as audit log entries.

Right to Erasure

To fulfil a GDPR erasure request for a contact:

await trpc.mailchimp.preferences.gdprDelete.mutate({ entityId, entityType });

This removes the contact's preference records and removes them from Mailchimp audiences in accordance with their erasure request.

Background Jobs Reference

Inngest Function	Trigger	Description
`mailchimp-scheduled-sync`	Cron — daily at 05:00 UTC	Iterates all connected orgs and dispatches segment sync events
`mailchimp-segment-sync`	Event-driven	Syncs a single segment to its mapped Mailchimp audience
`mailchimp-campaign-stats-refresh`	Cron — every 6 hours	Refreshes open/click rates for active campaigns

tRPC API Reference

All procedures are under the mailchimp namespace.

`mailchimp.connection`

Procedure	Type	Description
`get`	Query	Returns the current org's Mailchimp connection or `null`
`connect`	Mutation	Validates and stores the API key; input: `{ apiKey: string }`
`disconnect`	Mutation	Soft-deletes the connection
`listAudiences`	Query	Returns all Mailchimp audiences for the connected account

`mailchimp.segments`

Procedure	Type	Description
`list`	Query	Returns paginated segments; input: `{ limit?: number }`
`get`	Query	Returns a single segment by ID
`create`	Mutation	Creates a new segment
`update`	Mutation	Updates segment name, description, or filter criteria
`delete`	Mutation	Soft-deletes a segment
`sync`	Mutation	Triggers an immediate sync for a segment

`mailchimp.campaigns`

Procedure	Type	Description
`list`	Query	Returns tracked campaigns
`get`	Query	Returns a single campaign by ID
`trackCampaign`	Mutation	Imports a Mailchimp campaign for tracking
`refreshStats`	Mutation	Manually refreshes stats for a campaign

`mailchimp.preferences`

Procedure	Type	Description
`getForEntity`	Query	Returns preferences for a specific contact
`list`	Query	Returns all preferences for the org
`updateOptStatus`	Mutation	Records an opt-in or opt-out for a contact
`gdprDelete`	Mutation	Erases all preference data for a contact (right to erasure)

Database Tables

Table	Purpose
`mailchimp_connections`	Stores one API connection per org
`contact_segments`	Segment definitions with filter criteria and Mailchimp list mapping
`campaign_tracking`	Campaign metadata and performance statistics
`email_preferences`	Per-contact GDPR consent records

All connections and segments use softDeletedAt for non-destructive removal. All state-changing operations are written to the platform audit log.