Mailchimp Integration

import { Aside, Steps } from ‘@astrojs/starlight/components’;

The Mailchimp integration is in active development. This page documents the planned one-way migration so you can prepare your Mailchimp API key and know exactly what will be imported when it launches.

What it does

The Mailchimp integration is a one-way migration: it pulls everything you have in Mailchimp into HARi in a single guided run. After migration, you stop using Mailchimp for new sends and run campaigns from HARi instead. There is no ongoing two-way sync — that’s intentional, to keep the contact data clean and the consent state unambiguous.

What gets imported

From Mailchimp	Into HARi
Audiences (lists)	Tags on contacts (e.g. mailchimp:newsletter-readers)
Subscribers	Contact records, deduplicated by email across audiences
Subscription status (subscribed, unsubscribed, cleaned, pending)	email_consent_status field — preserved exactly
Merge fields (FNAME, LNAME, PHONE, custom)	Mapped to existing contact fields, or created as new custom fields
Tags	Tags on contacts (kept verbatim)
Member rating, VIP, language, signup IP/date	Custom fields on the contact
Sent campaigns	Email Campaign records with subject, send time, recipients, summary stats
Campaign HTML	Archived to S3 storage, viewable per campaign
Per-recipient engagement (opens, clicks, bounces)	Activity log entries on the contact’s timeline (opt-in — large datasets)

Subscription status preservation is non-negotiable: a contact who unsubscribed in Mailchimp arrives in HARi flagged as unsubscribed and is excluded from any future HARi campaign by default. This protects you from CAN-SPAM and GDPR violations on day one.

Before you start: generate a Mailchimp API key

You can do this today, before the integration ships. The key stays valid until you delete it.

1. Go to the Mailchimp API Keys page: https://us1.admin.mailchimp.com/account/api/

   Mailchimp may redirect you to your own datacenter (e.g. us13.admin.mailchimp.com) — that’s expected and harmless.

2. Click “Create New Key” and give the key a descriptive name. We recommend HARi CRM so you remember which integration it belongs to.

   

3. Click “Generate Key”. Mailchimp shows you the full key once — copy it immediately. After this screen, the key cannot be retrieved.

   

4. Note the datacenter. The key ends in -usXX (e.g. -us13, -us19). HARi uses this suffix automatically to route API calls to your datacenter — you don’t need to enter it separately.

5. Paste the key into HARi under Settings → Integrations → Mailchimp when the integration launches. The key is stored encrypted in your tenant database. It is never sent to any other tenant or to a shared environment variable.

Treat the API key like a password. Anyone with this key can read your full Mailchimp account — including subscriber emails. If you suspect it's leaked, regenerate it immediately from the same Mailchimp page (this also revokes the old one).

How the migration runs

1. Discover — HARi calls Mailchimp and reports back: how many audiences, how many subscribers, how many sent campaigns, how many custom fields. You see a summary like “3 audiences, 8,427 contacts, 142 campaigns, 27 custom fields” before committing.

2. Map fields — HARi auto-suggests a mapping (Mailchimp FNAME → HARi first_name, etc.) and lets you correct it. Unknown fields can be created automatically as custom fields on the contact entity.

3. Choose policies — set how to handle:

   • Audience policy: import as tags (recommended), as a list field, or as separate static lists
   • Conflict policy: skip / update / create-with-suffix when an email already exists in HARi
   • Engagement detail: import per-recipient opens and clicks (large) or campaign-level summaries only (recommended for first run)

4. Run — the migration runs as a background job with a progress UI. You can close the browser; it keeps running. Each stage checkpoints, so a failure mid-run doesn’t restart from scratch.

5. Reconciliation — at the end you get a report: X contacts created, Y updated, Z skipped, A campaigns imported, B engagement events logged. Any errors come with a CSV download.

Phased rollout

Migration is shipping in three phases:

Phase	Scope	Status
1	API key auth, single audience, contacts + status + tags + field mapping, reconciliation report	In development
2	Multi-audience, campaign metadata + HTML archive	Planned
3	Per-recipient engagement events into contact timelines, segment recreation as HARi saved views	Planned

Phase 1 covers most of the value: your contact list lands in HARi cleanly with consent state preserved, and you can start running campaigns from HARi the same day. Phase 2 and 3 are about historical visibility (which campaigns went out, who opened what) — useful but not blocking.

What’s intentionally out of scope

• No two-way sync. The integration migrates Mailchimp → HARi once. New subscribers added to HARi after migration do not flow back to Mailchimp. The point is to leave Mailchimp behind, not to maintain it as a parallel system.
• No automation/customer-journey migration. Mailchimp Classic Automations and Customer Journeys don’t transfer — you re-build the equivalent in HARi’s automation builder. Sent emails from past automations do come over as campaign records.
• No Mailchimp Transactional (Mandrill). Different product, different API. Use HARi’s transactional email instead.
• No template porting. Mailchimp templates stay where they are. HARi has its own template editor; archived campaign HTML can be a starting point.

FAQ

Will it import unsubscribed and bounced contacts? Yes — and they stay flagged as such. This is mandatory for compliance. They count toward your contact total but are excluded from any new send unless you explicitly re-opt them in.

What happens if the same email exists in three Mailchimp audiences? One contact in HARi with three tags, not three duplicate contacts. Email is the deduplication key.

Can I run the migration twice? Yes — it’s idempotent. Re-running upserts on the contact email and on the Mailchimp campaign ID, so nothing gets duplicated. This is useful for catching late changes between your test run and your real cutover.

How long does the migration take? Roughly 1 minute per 1,000 contacts plus 10 seconds per past campaign (campaign HTML archiving) plus 30 seconds per 10,000 engagement events (Phase 3 only). A typical SME with 5,000 contacts and 50 campaigns finishes in under 10 minutes.

What if my list is huge (>500k)? We use Mailchimp’s bulk export API for the initial dump (gzipped CSV, single call) and the regular API for everything else. No practical size cap.

Will my Mailchimp account be modified? No. The integration only reads from Mailchimp — never writes, deletes, or unsubscribes anything. You decide when (or if) to close your Mailchimp account.

Request early access

Want to be in the first wave to migrate? Contact us and we’ll prioritise your tenant.