How to migrate from Mailchimp to listmonk

Move from Mailchimp to self-hosted listmonk: export every audience, import the blocklist first, keep opt-in records, rebuild templates and warm up a new domain.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

In short

  • A Mailchimp audience export can come as a ZIP with one CSV per contact status; each file is reshaped to email, name and a JSON attributes column that carries merge fields, tags and opt-in records.
  • Unsubscribed and cleaned contacts are imported to the listmonk blocklist first, so no later import can subscribe them again.
  • Drag-and-drop templates cannot be exported from Mailchimp, journeys have no counterpart in listmonk, and campaign reports stay in Mailchimp’s exports.
  • listmonk sends one-click unsubscribe headers, while SPF, DKIM and DMARC belong to the sending domain and the relay you choose, and a new domain is warmed up on engaged subscribers first.
On this page (11)

Moving from Mailchimp to listmonk is an import, a rebuild and a change of sending infrastructure. Subscribers come across with their fields, tags and opt-in records; history does not. Templates built in Mailchimp’s drag-and-drop editor are rebuilt, journeys have no counterpart, and campaign reports stay in Mailchimp’s exports. The import itself is the easy part. The care goes into two places: consent, so that nobody who unsubscribed or bounced is mailed again, and the sending domain, because listmonk hands every message to a relay you choose. Pilae does not operate mail. This guide covers the order we run it in, and the places it usually goes wrong.

Why teams move from Mailchimp to listmonk

Three reasons come up again and again.

  • The list stays with you. A subscriber list is personal data with consent attached. With listmonk on your own machines, subscribers, opt-in records and every campaign sit in a PostgreSQL database in the location you choose.
  • No bill that grows with the list. Mailchimp bills its plans on your contacts and email sends. listmonk has no paid edition and no fee per subscriber or per message; the costs are the machine, its operation and the relay.
  • Sending and tracking on your terms. You choose the relay and the rate it sends at. View and click tracking can be counted without being tied to a person, or switched off, and subscribers can export or wipe their own data from the public pages.

What you give up is real: customer journeys and other automations, landing pages, the drag-and-drop designs you already have, campaign history inside the tool, and a sending reputation that Mailchimp manages for you. The last one is the part that needs the most attention.

Step 1: export every audience and the account

Take every export before you change anything, and keep them under the retention rules for personal data.

  1. Each audience. In Mailchimp, click Audience, choose the audience from the drop-down if there are several, click Export audience, then Export CSV. Only Owners and Admins can export audiences. Mailchimp emails you when the export is ready, and it stays in the account only for a limited time, so download it at once.
  2. What the file holds. The export can come as a ZIP with a separate CSV for each type of contact: subscribed, unsubscribed, non-subscribed and cleaned. Each file has your audience fields, the marketing permissions of a GDPR-enabled audience, TAGS, NOTES, MEMBER_RATING, OPTIN_TIME and OPTIN_IP from the signup form, CONFIRM_TIME and CONFIRM_IP from the confirmation email, the location and time zone Mailchimp derived, LAST_CHANGED, and the LEID and EUID identifiers.
  3. Archived contacts. They are not in those four files. Export them separately, as a single-type export, to review in step 2.
  4. The account export. Under your profile, Account, Settings, Manage my data, Mailchimp builds a ZIP with your sent campaigns as HTML and text, the reports as aggregate and detailed activity, the email templates as HTML, and the audiences. Mailchimp limits how often it can be run, and a large account can take hours, so request it early.
  5. Custom-coded templates. Under Campaigns, Email templates, each template’s More options menu has Export as template, which downloads an HTML file. Mailchimp’s own help is plain about the rest: drag-and-drop templates cannot be exported.

Then write down what has no file: each customer journey with its trigger and steps, each signup form and where it is embedded, and every integration that adds contacts to Mailchimp, such as a website plugin, a shop or a CRM.

Step 2: map audiences, statuses and fields

Most of Mailchimp has a direct counterpart in listmonk. A few things do not, and the inventory finds them before the import.

Mailchimp listmonk
Audience List, single or double opt-in
Audience fields (merge fields) Name, and keys in the subscriber’s attributes
Tags An array in the attributes
Groups Separate lists, which subscribers manage on their preferences page
Segment SQL expression over the attributes; the results can go into a list
Signup form Subscription form generated under Lists, Forms
Merge tags Go template expressions
Customer journeys No counterpart: n8n drives them through the API
Reports Kept in the account export; listmonk starts its own from day one

Every status has a destination

The status of each contact decides how it is imported, and this is where a migration either keeps its consent records or loses them.

Mailchimp status What it means in Mailchimp In listmonk
Subscribed Opted in to your marketing Confirmed on the audience’s list
Unsubscribed Received your marketing, then opted out Blocklist, or unsubscribed on that list alone (see below)
Cleaned Undeliverable, after hard bounces or repeated soft bounces Blocklist
Non-subscribed Interacted with you, never opted in to marketing Not in any list that campaigns go to
Archived Removed from the audience Reviewed; to the blocklist if at all, never as subscribed

Why the blocklist. listmonk sends no campaign to a blocklisted subscriber, on any list. And when a later import in subscribe mode meets an address that is already blocklisted, listmonk keeps it blocklisted and marks the new subscription unsubscribed. So importing unsubscribed and cleaned contacts to the blocklist first protects them from every file that comes after: the subscribed import, a re-export a week later, or a CSV from a shop. A migration that leaves those two files behind mails people who already said no, and addresses that already bounced.

When to use per-list unsubscribes instead. A Mailchimp unsubscribe applies to one audience; a listmonk blocklist applies to everything. With a single audience, the blocklist is the right answer. With several, someone who left the events audience but still reads the newsletter would lose the newsletter too. For them, the import API marks the subscription unsubscribed on that one list, and the blocklist is kept for those who left every audience and for cleaned addresses.

Opt-in records go into the attributes. OPTIN_TIME, OPTIN_IP, CONFIRM_TIME, CONFIRM_IP and the marketing permissions are the evidence of each subscriber’s consent. Carry them into the attributes under a key of their own, and keep the original export as the record. A subscriber’s date in listmonk is the date of the import, not of their signup.

Step 3: reshape and import the subscribers

listmonk imports a CSV, or a ZIP holding a single CSV, with an email column, an optional name and an optional attributes column holding JSON, its quotes doubled as CSV requires. Each Mailchimp file is reshaped into that form: the first and last name join into name, and everything else goes into attributes.

email,name,attributes
anna.keller@example.com,Anna Keller,"{""mailchimp"": {""optin_time"": ""2024-03-02 09:14:11"", ""optin_ip"": ""203.0.113.24"", ""confirm_time"": ""2024-03-02 09:15:40"", ""confirm_ip"": ""203.0.113.24"", ""leid"": ""123456789""}, ""company"": ""Acme"", ""country"": ""CH"", ""tags"": [""customers"", ""events""]}"

Create the lists first, one per audience, as single or double opt-in like the audience was. Then import in this order, from Subscribers, Import, or through the import API.

  1. The blocklist. Cleaned contacts, and unsubscribed ones where they go to the blocklist, in blocklist mode. No list is selected: blocklisting applies to the whole instance.
  2. The subscribers. Each audience’s subscribed file in subscribe mode, with the status Confirmed, into its list. On a double opt-in list, only confirmed subscribers receive campaigns; importing them as confirmed carries over the opt-in they gave Mailchimp, which their attributes record.
  3. Per-list unsubscribes. Where step 2 chose them, through the API, in subscribe mode with the subscription status unsubscribed. The import screen offers only unconfirmed and confirmed in subscribe mode.
# 1. Cleaned and unsubscribed contacts to the blocklist (no list)
curl -u "api_user:token" -X POST 'https://listmonk.acme.internal/api/import/subscribers' \
  -F 'params={"mode":"blocklist", "delim":","}' -F "file=@blocklist.csv"

# 2. The newsletter audience, confirmed, into list 3
curl -u "api_user:token" -X POST 'https://listmonk.acme.internal/api/import/subscribers' \
  -F 'params={"mode":"subscribe", "subscription_status":"confirmed", "delim":",", "lists":[3]}' \
  -F "file=@newsletter-subscribed.csv"

# 3. People who left the events audience only: unsubscribed on list 4
curl -u "api_user:token" -X POST 'https://listmonk.acme.internal/api/import/subscribers' \
  -F 'params={"mode":"subscribe", "subscription_status":"unsubscribed", "delim":",", "lists":[4]}' \
  -F "file=@events-unsubscribed.csv"

One import runs at a time, and since a blocklist import applies to every list, it is run by an administrator. When an address already exists, its name and attributes, and the status of its existing list subscriptions, are kept unless two separate switches say otherwise: Overwrite user info and Overwrite subscription status. Leave the subscription status switch off on every re-run. listmonk warns that overwriting it re-subscribes unsubscribed addresses.

Check the result before anything is sent: confirmed subscribers per list against Mailchimp’s subscribed count, blocklisted subscribers against the cleaned and unsubscribed files, and the import log for every line it skipped.

Step 4: rebuild templates, segments and forms

Templates. Campaign templates live under Campaigns, Templates, as HTML with Go template expressions, and the expression {{ template "content" . }} appears once in each, where the campaign body goes. A custom-coded Mailchimp template comes across as HTML once its merge tags are replaced. A drag-and-drop design is rebuilt, in listmonk’s visual builder or as HTML, with the sent campaign’s HTML from the account export as the reference.

  • *|FNAME|* becomes {{ .Subscriber.FirstName }}, which listmonk takes from the name. Other merge fields become attributes: a field imported as company is {{ .Subscriber.Attribs.company }}.
  • *|EMAIL|* becomes {{ .Subscriber.Email }}.
  • *|UNSUB|* becomes {{ UnsubscribeURL }}, and *|UPDATE_PROFILE|* becomes {{ UnsubscribeURL }}?manage=true.
  • *|ARCHIVE|* becomes {{ MessageURL }}.
  • *|LIST:ADDRESS|* becomes your postal address, written into the footer.
  • Conditional merge tags become {{ if }} blocks over the attributes.

Template expressions run with a large function library, so listmonk advises giving template and campaign permissions only to trusted users. Send every rebuilt template to a seed list of your own addresses at the common mailbox providers before it reaches a subscriber.

Segments. A segment becomes an SQL expression over the subscriber fields and attributes, and its results can be added to a list for a campaign.

-- Tagged "customers" in Mailchimp, and based in Switzerland
subscribers.attribs->'tags' ? 'customers' AND subscribers.attribs->>'country' = 'CH'

Forms and integrations. Each Mailchimp signup form is replaced with a listmonk subscription form: Lists, Forms generates the HTML for public lists, and a double opt-in list sends the confirmation email itself. Integrations that added contacts to Mailchimp move to listmonk’s subscriber API. Journeys such as a welcome series are rebuilt in n8n, which finds new subscribers with a query through listmonk’s API and sends each step through its transactional API.

Step 5: set up the relay, the domain and bounces

listmonk neither delivers mail to recipients nor signs it with DKIM. It hands every message to SMTP servers you configure, and the relay does the rest. Pilae does not operate mail, so the relay is your own server or a sending provider you contract.

  • The relay. Under Settings, SMTP, add one or more servers with their host, port, credentials and TLS mode. A server can be tied to particular From addresses or domains, and servers given the same entry are used in turn. Some relays require a real hostname in the HELO greeting, which is a setting of its own.
  • The rate. Under Settings, Performance, the concurrency and the message rate per worker set how fast listmonk sends, and the sliding window caps how many messages go out in a period. Set both below what the relay accepts.
  • The domain. Publish SPF for the relay and the DKIM key it signs with, and a DMARC record, with the domain in the From address aligned with the SPF or the DKIM domain.
  • The bounces. Under Settings, Bounces, turn bounce processing on. Either listmonk scans a dedicated POP3 mailbox, set as the Return-Path in the SMTP server’s custom headers, and deletes each bounce after processing it, or your provider posts bounces to a webhook: Amazon SES, SendGrid and Postmark are among those listmonk supports. Blocklist hard bounces and complaints at the first occurrence, and soft bounces only after several.

Gmail and Yahoo require one-click unsubscribe

Google’s sender guidelines ask anyone sending more than 5,000 messages a day to Gmail accounts for SPF and DKIM, a DMARC record (a policy of none is accepted), a From domain aligned with SPF or DKIM, one-click unsubscribe with the List-Unsubscribe-Post: List-Unsubscribe=One-Click header, a clearly visible unsubscribe link, and a low spam rate in Postmaster Tools, under the ceiling the page sets. Yahoo’s requirements are close: SPF, DKIM and a passing DMARC policy of at least none, a one-click List-Unsubscribe header, a visible unsubscribe link, unsubscribes honoured within a short deadline and a spam rate under the same ceiling.

listmonk covers the headers. With Include List-Unsubscribe header on, under Settings, Privacy, every campaign carries List-Unsubscribe with the subscriber’s own unsubscribe address and List-Unsubscribe-Post: List-Unsubscribe=One-Click, and a POST to that address unsubscribes at once. {{ UnsubscribeURL }} in the template footer is the visible link. The rest belongs to the domain and the list, which is why both are part of the move.

Step 6: warm up the new sending, then close Mailchimp

A domain or IP address that has not sent this volume before has no reputation yet. Google’s guidelines say to start with a low volume to engaged users, increase it slowly, and send at a consistent rate rather than in bursts. Mailchimp’s member rating, carried across in the attributes, picks out the most active subscribers for the first sends.

The cutover, in order

  1. Forms: Signup forms and integrations point at listmonk; Mailchimp stops receiving new contacts.
  2. Last export: A final audience export is imported, the blocklist first, without overwriting subscription status.
  3. Seed: A test campaign goes to your own addresses at the common mailbox providers.
  4. Warm-up: The first campaigns go to the most engaged subscribers at a reduced rate, rising with each send.
  5. Close: Late unsubscribes are blocklisted, reports and the account export are kept, and the account closes.

Unsubscribe links in emails Mailchimp already sent point at Mailchimp. Export the unsubscribes that arrive there during the overlap and blocklist them in listmonk, once more on the last day. After the account closes, remove the DNS records you published to authenticate your domain with Mailchimp.

Running listmonk in production

listmonk is one Go binary with PostgreSQL behind it, so a production instance is small.

  • PostgreSQL holds subscribers, campaigns, templates and every setting, SMTP credentials included. Its backup is the whole configuration.
  • The uploads directory holds campaign images, and is backed up with the database.
  • Admin private, reader paths public. The admin and the API stay on the private network. Subscription pages, unsubscribe and tracked links, the tracking pixel, uploaded images and the provider bounce webhooks are the routes listmonk documents for the internet.
  • Upgrades. A release can change the database schema (listmonk --upgrade), and an upgraded database is not used with an older binary, so the way back is the backup taken just before. An upgrade never runs while a campaign is sending.

Pilae operates listmonk this way: the admin and API only on your private network, behind Keycloak or Entra ID over OpenID Connect, and the reader paths and bounce webhooks through the Pilae gate on port 443. The database and uploads are backed up daily, encrypted, to the country your contract names, and on Enterprise a restore test every month recorded in the console, run with outbound mail pointed at a sink so it never reaches a subscriber. Upgrades go through the Pilae Agent, tried on a copy and applied in your window, between campaigns. It runs on your premises or on dedicated machines in Pilae Cloud.

Let Pilae run the move

Pilae runs Mailchimp to listmonk migrations at a fixed price: the audience and account exports, the mapping of statuses and fields, the import with the blocklist first, the template and form rebuild, the domain and bounce setup with the relay you choose, and the warm-up and cutover. Then we operate listmonk for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us about your audiences and we will scope it.

Questions

Can listmonk import a Mailchimp export directly?

Not as it comes. A Mailchimp audience export can come as a ZIP with one CSV file per contact status, and listmonk imports one CSV at a time with an email column, an optional name and an optional attributes column holding JSON. Each file is reshaped first: merge fields, tags and opt-in records go into the attributes, and the status decides how the file is imported.

What happens to unsubscribed and cleaned contacts?

They come across, to the blocklist. listmonk sends no campaign to a blocklisted address, and an import in subscribe mode keeps a blocklisted address blocklisted, so importing them first means no later file can subscribe them again. Where an organisation has several audiences and someone left only one of them, the import API can mark them unsubscribed on that list alone.

Do the opt-in records come across?

Yes, as attributes. Mailchimp's export carries the signup and confirmation times and IP addresses, and the marketing permissions of GDPR-enabled audiences, for each contact. They go into each subscriber's attributes, and the original export is kept as the record. From then on, listmonk records double opt-in confirmations itself and can store the IP address of each one.

Does listmonk meet the Gmail and Yahoo bulk sender rules?

listmonk does its part: with its List-Unsubscribe setting on, every campaign carries the List-Unsubscribe and List-Unsubscribe-Post headers, and an unsubscribe link goes in the template footer. SPF, DKIM, DMARC and the spam rate belong to the sending domain and the relay, which is why they are part of the move.

Is listmonk open source?

Yes. It is AGPL-3.0, with no paid edition and no fee per subscriber or per message. OpenID Connect sign-in, bounce processing, the import and the API are all in the one build. The cost outside its operation is the relay or sending provider, which you contract directly.

How long does a Mailchimp to listmonk migration take?

It depends on the number of audiences and templates, and above all on the sending domain: a new relay, domain or IP address is brought up to full volume over several campaigns, not in one. Pilae quotes the export, the import, the rebuild and the cutover at a fixed price once the audiences and templates are listed.

Let us run the move for you

An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.

Start with one workload

  • Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
  • CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.