How to import contacts into Mautic from another platform without losing consent or history
Contacts load into Mautic through a documented CSV import, and the effort depends mainly on three things: the quality of the data you export, whether consent and preference fields survive the export in a usable form, and how many integrations and automations must be rebuilt on the Mautic side. Start by inventorying those three before you export anything. Pull a sample of records from each list you plan to move and check whether every contact has an email address, a clear opt-in or opt-out status, a date that shows when that status was recorded, and the tags or segment memberships that drive your current sends. Records that lack a consent source or date are the ones most likely to cause trouble later, so decide now whether you will migrate them, hold them back or re-permission them.
Contact import is only one part of a platform switch. Forms, landing pages, email templates, campaign logic, CRM sync and sending domains all have to work before the old tool is retired, and each of them depends on the order in which you change things. Plan the sequence explicitly: which contact lists move first, which automations are rebuilt and tested, when sending domains and tracking are switched, and when the old platform stops accepting new sign-ups. The sequence determines what can break and in which order, so write it down as a runbook with a named owner for each step and a rollback point for each stage.
Plan a parallel run before you cut over. For a defined period, both platforms receive the same data or the same sends are compared, so that unsubscribes, bounces and complaints are confirmed as recorded in Mautic before the old system is switched off. Use the parallel run to check suppression behavior specifically: a contact who unsubscribed in the old tool must remain suppressed in Mautic, or you risk emailing people who withdrew consent. Confirm with your legal or privacy team how the consent evidence from the old platform will be retained, because the import file will carry the status but may not carry the full history of how consent was given.
Ask the people involved to confirm several items before the project starts. Confirm with your current vendor which export formats and fields are available for your plan, including consent timestamps and suppression lists, and whether the export is complete or limited to active contacts. Confirm with your Mautic implementation team how custom fields, tags and date formats will be mapped, and whether the import will be run in the browser or by background cron job for your volumes. Confirm the Mautic release you will deploy and its support window with the Mautic releases page before the build starts, since that date affects how long the new environment can run without an upgrade.
The practical outcome of this section is a decision record: which contact sets migrate, which consent fields are authoritative, how history is retained outside Mautic if it is not imported, who approves each cutover step, and what evidence will show that the parallel run matched. Without that record, the CSV file itself is the least risky part of the project, and the decisions around it carry most of the risk. Treat the import as the final step of a verified plan rather than the start of one.
Which contact data maps cleanly into Mautic and which needs rebuilding
This table compares common capabilities from a previous marketing platform with their Mautic equivalents and shows whether each one arrives as CSV data, must be rebuilt in Mautic, or may not transfer. Use the Path column to plan the import and the migration note to decide what your team recreates by hand. If you cannot find an item in the Mautic import documentation, confirm its handling with Mautic and in a test import before you assume it moves.
| Source capability | Mautic equivalent | Path into Mautic | Migration note |
|---|---|---|---|
| Contact fields | Standard contact fields | CSV column | Map each header to a Mautic field and confirm which field Mautic uses to match existing contacts. |
| Custom fields | Contact custom fields | CSV column | Mautic auto-maps headers that match field names, so create missing fields before importing. |
| Tags | Contact tags | CSV column | Separate multiple tags with a pipe character, and replace any other delimiter in the source export. |
| Lists or segments | Segments | Rebuild as segment | Export list membership as a tag or field, then recreate the filters as Mautic segments. |
| Consent and unsubscribe status | Do not email flag (doNotEmail) | CSV column | Accepts true, 1, on or yes. Keep consent evidence in your records, because the flag alone may not prove consent. |
| Timestamps | Date fields | CSV column | Use ISO 8601 format (YYYY-MM-DD hh:mm:ss). Confirm whether created dates can be set on import. |
| Campaigns and automations | Campaigns | Rebuild as campaign | Recreate sequences and triggers. Campaign updates depend on cron jobs, so source workflows will not run automatically. |
| Email send history and engagement | Activity history | May not transfer | Confirm with the import documentation. Archive source reports now so the history stays available for audits. |
| CRM sync | HubSpot or Salesforce plugin | Rebuild as integration | Reconnect and configure the integration in Mautic. Sync settings are not contact data and do not come across in a CSV. |
What the CSV file must look like before Mautic accepts it
Before anyone clicks upload, the file has to meet a short set of rules that Mautic documents for contact imports. The file must be a CSV encoded as UTF-8. Boolean fields such as doNotEmail accept true, 1, on or yes, so the export should be converted to one of those values rather than left as the source tool's own wording. When a contact belongs to several tags, the tags go in one cell separated by a pipe character. Date-times should follow ISO 8601 in the form YYYY-MM-DD hh:mm:ss. A data owner can check these rules with a spreadsheet, but the check is only useful if someone compares the actual column contents against the rules, row by row for the columns that matter.
Mautic maps columns automatically when a CSV header matches the name of an existing contact custom field, so renaming headers to match Mautic's field names before upload saves manual mapping work. Confirm the exact field names in your own instance under the contact field settings, because a header that looks identical but differs in case or spacing may not match. The import screen also offers an option to skip fields that already hold a value on the contact. Decide this before the import starts. If the goal is to fill gaps only, enable the option. If the new file is the more current source and should overwrite older values, leave it off and agree that decision with the marketing owner in writing.
Exports from older tools often need cleaning first. Files saved from legacy systems may carry a non-UTF-8 encoding, which turns accented names into unreadable characters. A single source may mix date formats such as day-first and month-first dates in the same column, which makes dates ambiguous. Duplicate email addresses are common when contacts were added from several forms or lists, and they cause a single person to be imported more than once or updated unpredictably. Blank rows, trailing spaces and inconsistent country or consent values also appear frequently.
A pre-import check should catch these problems before Mautic sees the file. It should confirm the encoding, the header names, the boolean values, the tag separator, the date format, the number of rows with missing email addresses, and the number of duplicate emails after normalizing case and spacing. Ask the data owner to sign off on how duplicates are resolved and which source wins when two records conflict. Keep a copy of the original export so the cleaning steps can be reviewed or repeated. Large files also need splitting into smaller parts, and the import method depends on that size, so confirm the approach with whoever will run the import before the file is finalized.
Documented import paths Mautic offers for contact data
Mautic's contact import documentation is the authority for what the software supports. The options below fall into two groups: ways to load a CSV file into Mautic from the browser or by cron, and CRM plugins that send contacts outward to an external system. Confirm current behavior for your release in the Mautic documentation before you choose a path.
Browser contact import
The browser import uploads a UTF-8 CSV through the admin interface and processes it in batches while the browser window stays open. It suits small lists and test loads where someone can watch progress and fix errors. Prepare the file with headers that match contact field names, pipe-separated tags, ISO 8601 dates and boolean values such as true, 1, on or yes. Closing the window can interrupt the run, so confirm the batch behavior on your release before loading a large list.
Background import by cron
A background import runs through cron, so the job continues after the browser closes. Mautic recommends this path for larger files, and it shares the scheduler with segment, campaign and trigger jobs that the documentation says should be staggered. Check that the import command runs on your schedule, that the server has capacity for the import alongside those jobs, and that someone can read job status and error output. Confirm the command name and options in the documentation for your release.
Splitting large CSV files
Mautic recommends splitting CSV files that contain more than a few thousand contacts. Smaller parts are easier to validate, to re-run after a failure and to reconcile against the source export. Each part should carry the same header row and UTF-8 encoding, and the team should record which parts loaded and how many contacts each one added. Plan the split before the cron job starts so that any failure can be isolated to a single file.
HubSpot plugin sync
The HubSpot plugin sends Mautic contacts to HubSpot CRM when contact actions or point triggers fire. It suits teams that keep HubSpot in use during a transition and need contact changes to reach it, but it does not load a legacy list into Mautic. Decide which fields and triggers sync, who owns duplicate handling, and what happens to contacts that already exist in HubSpot. Confirm the plugin setup steps for your release in the HubSpot plugin documentation.
Salesforce integration
Mautic's documentation includes a Salesforce integration page for connecting Mautic to an external CRM. Treat it as a separate project from the CSV load, since it moves data between systems instead of loading a file. Before you enable it, confirm from the Salesforce plugin documentation for your release which objects sync, which direction data flows, and which Salesforce permissions and API access the connection needs. Agree the field mapping and duplicate rules with the team that owns Salesforce.
How a contact migration runs from inventory to cutover and decommission
The sequence moves contacts and consent records from the previous tool into Mautic in checked stages, so each stage has a signed output before the next begins. Sending moves to Mautic only after counts and consent flags reconcile, and the old tool is removed only after its retention period ends.
Inventory source data and consent records
Export every contact list, tag, custom field, suppression list and bounce record from the previous tool. For each list, record row counts, the forms or sources that collected consent, the date and wording of that consent, and any unsubscribe or do-not-email status. Marketing operations leads this work, and the privacy lead reviews the consent fields. The step is complete when the data owner and privacy lead sign off on a written inventory that lists every source file and its consent basis.
Define the Mautic contact model and field mapping
Decide which source fields become Mautic contact fields, which become tags and which are retired. Mautic auto-maps CSV headers that match existing contact custom field names, so name new custom fields to match the planned headers where possible. Set the target formats in the mapping sheet: UTF-8 encoding, booleans as true, 1, on or yes, multiple tags separated with a pipe, and dates in ISO 8601 (YYYY-MM-DD hh:mm:ss). The output is a mapping sheet approved by the marketing operations lead and the data owner.
Run a pilot import on a sample
Build a sample CSV that includes the awkward cases: accented names, duplicate email addresses, empty consent fields, multi-value tags, and dates in mixed formats. Import it into a non-production Mautic instance and decide whether the skip-existing-value option suits your data. Review each row that failed or landed in an unexpected field, then correct the mapping or source file and repeat. The pilot is complete when the sample imports without unexplained errors and the engineer and marketing operations lead both sign off on the results.
Reconcile counts and consent flags
Compare row counts from the source inventory with contact counts in Mautic, and list every duplicate, rejected row and contact missing a consent value. Check that do-not-email flags and consent tags match the source records for a random and a targeted sample of contacts. Contacts without a verifiable consent basis are imported as non-marketable or held back, according to the privacy lead's decision. The step closes when the privacy lead signs off on a reconciliation report with every exception explained.
Run the full import and start the parallel run
Split files that contain more than a few thousand contacts, then run the full import as background jobs by cron rather than through a browser session, because browser imports depend on the window staying open. Keep the previous tool live for lookup and fallback during the parallel run, but assign each audience to one sending tool only. Sends must not run from both tools for the same audience during the parallel run. The output is an import log and a second reconciliation report, both signed off by the marketing operations lead.
Cut over sending and integrations
Stop campaigns in the previous tool for each audience, then point sending domains, forms, landing pages, CRM sync and webhooks at Mautic. Confirm that the cron jobs for segment updates, campaign updates and campaign triggers run on staggered schedules, and that the broadcasts command and messenger consumer run if email is queued. Test one send per audience and one CRM sync before closing the old sending path. The output is a cutover record signed off by the marketing lead and the platform owner.
Decommission the old tool after retention
When the retention period in your data retention policy ends, export a final archive of the previous tool's data and store it under the access controls your privacy team sets. Revoke API keys and integration credentials, remove sending accounts, and delete or archive personal data as the policy requires. Confirm that no inbound forms or scheduled jobs still point at the old tool. The step is complete when the privacy lead signs off a decommission record that names the archive location and the deletion evidence.
When to split a CSV and run the import in the background by cron
Split the file and run the import by cron when the list is large. Mautic's documentation recommends background imports for larger files and for CSVs with more than a few thousand contacts. The reason is how browser imports work: they run in batches that depend on the browser window staying open. If a laptop sleeps, a VPN drops or someone closes the tab, the import stops partway through. A background job does not depend on anyone's session, so it can finish a long file that a browser import would never complete reliably. Decide the split threshold before the migration starts, and test it with a copy of the real export so the team knows how the import behaves on your data and hardware.
A background import creates operational work that a browser import does not. Someone must own a scheduled job, know where its output goes and be able to read the logs when a batch fails. Plan for access to the application logs and the web server logs on the host, and make sure the person watching them can see both. After each batch, check that counts match. Compare the number of data rows in the part file (excluding the header) with the contacts created, updated and skipped, and record any rows that were rejected. Each split file needs its own header row, UTF-8 encoding and the same field order, so verify those before the job runs rather than after a failure.
Schedule the import alongside the rest of the cron plan, not on top of it. Mautic's cron jobs for segment updates, campaign updates and campaign triggers are meant to be staggered. A large import changes many contact records, which can make the next segment update or campaign trigger run heavier than usual. Put the import in a window that does not overlap those jobs, and sequence the batches so segment rebuilds run after each import finishes. Also check that any email sending or messenger processing your setup depends on is not competing for the same server resources during the import window.
Confirm the exact command, its arguments and the cron configuration in the Mautic documentation for the version you run, before writing any crontab entry. Check how the import command is invoked, which file path and user it needs, whether it expects the file in a specific directory, and how it reports progress and errors. Confirm whether any messenger consumer or other background worker must be running for the import to complete. Test the full sequence on a non-production instance with a small split file, then with a larger one, and keep the documented steps with the migration runbook so the next person can repeat them.
What drives the cost and duration of a Mautic contact migration
This table lists the factors that move the cost and schedule of moving contacts into Mautic, whether each one is paid once or recurs, and which direction it pushes the effort. Use it to compare what each driver will add to your own source data before you request a quote, since most overruns come from data quality and consent history rather than from file size.
| Driver | One-time or recurring | Effect on cost and duration | What to ask for or confirm |
|---|---|---|---|
| Data quality and number of source fields | One-time | More fields and inconsistent values raise mapping and cleansing effort | Field inventory with sample values and the agreed mapped field list |
| Consent and preference model | One-time | Mapping opt-in, opt-out and channel preferences to Mautic settings adds review and legal sign-off time | Written consent mapping rules approved by your data protection owner |
| Number of segments to rebuild | One-time | Each segment needs its logic re-created and tested against imported contacts | Segment list with rules and expected counts for validation |
| Campaigns and forms to rebuild | One-time | Each campaign or form adds design, build and test work and possible integration changes | Inventory of campaigns and forms in scope, including which ones are excluded |
| CRM and other integrations | One-time, with recurring sync checks | Each connected system adds mapping, sync rules and monitoring | Integration list, sync direction and the owner for each system |
| Volume of contacts and file splitting | One-time | Larger files need splitting and background cron imports, extending run time | Number of import runs and the batch approach proposed |
| Number of pilot cycles | One-time | Each pilot repeats import, review and correction, so more cycles add effort | Number of pilot cycles included and what each one must prove |
| Parallel-run period | Recurring until cutover | Running old and new systems together keeps two sources of truth and extra checks | Length of the parallel run and who signs off the cutover |
| Reconciliation method | One-time, with recurring checks | Count, sample and field-level comparisons add reporting work at each run | Reconciliation method, tolerances and the report format delivered |
What usually goes wrong when contacts move into Mautic and how to prevent it
Most contact migrations into Mautic fail in predictable places: consent flags, duplicate records, dates, tags and the tools that still point at the old platform. Each risk below comes with a specific check to run before the import, during the parallel run and at cutover.
Consent flags imported incorrectly
Mautic reads the doNotEmail column and similar booleans from the file, and accepts true, 1, on or yes as values. A column exported with other labels, or with blank cells that should mean opted in, can silently mark contacts as sendable or block people who unsubscribed. Before the full import, run a pilot file of a few hundred rows and reconcile suppression counts against the source platform's unsubscribe and bounce reports.
Duplicate contacts from email case
Email addresses that differ only in capitalization can create second records in Mautic, which splits engagement history and can send the same person two campaign messages. Normalize addresses to lowercase and trim whitespace in the source file, then count unique addresses before and after the import. Keep the duplicate report from the pilot as a sign-off artifact.
Dates parsed in the wrong format
Mautic expects ISO 8601 date and time values in the form YYYY-MM-DD hh:mm:ss. Exports that use day-first or month-first formats, or locale-specific separators, can be read as the wrong date or rejected, which affects segment rules that depend on sign-up or last-activity dates. Write the expected format into the field map and spot-check a sample of dated rows against the source before going further.
Tags lost or split incorrectly
Mautic separates multiple tags with a pipe character, so a source value that uses commas, semicolons or a different delimiter can produce one long tag or drop tags entirely. Segments and campaigns built on those tags then select the wrong audience. Document how each source tag maps to a Mautic tag, including naming rules, and compare tag counts per tag between the two systems.
Double sending during the parallel run
While both platforms are live, the same contact can receive a campaign from the old tool and from Mautic. Prevent this with a send freeze list: a named set of segments or contacts that are excluded from sends in the source platform for the parallel period, owned by one person who signs off each change. Confirm the freeze is applied before the first Mautic campaign goes live.
Integrations still pointing at the old tool
Web forms, landing page scripts, webhooks, CRM syncs and reporting dashboards can keep writing to or reading from the previous platform after cutover, so new sign-ups never reach Mautic. Build an integration checklist that lists every inbound and outbound connection, its owner, and its switch-over step, and verify each one with a test record after the cutover. Keep the old platform's connections disabled but not deleted until the checklist is complete.
Questions buyers ask before importing contacts into Mautic
How much does a Mautic contact import cost?
Cost follows from a written scope. DeployOpen does not publish a price list, so a quote is based on the files, fields and sources you agree to cover. The main components are discovery of the source export, field mapping and cleaning, the import runbook, running and verifying the load, and handover documentation. Costs rise with the number of source platforms, the number of custom fields that need a decision, the amount of cleaning required (duplicates, malformed dates, missing owners), and whether consent records must be reconciled against evidence from the old tool. Most of the work is one-time. Recurring costs appear only if you add repeat imports or a support retainer, which is available separately. When you request a quote, ask which files and fields are covered, who validates the result, and what acceptance looks like.
How long does importing contacts into Mautic take?
The duration depends on file size, the number of files, data quality and how many people must sign off, so no single timeline fits every import. Browser imports run in batches only while the browser window stays open, which is why Mautic recommends background imports by cron for larger files and splitting CSVs that hold more than a few thousand contacts. Processing time then depends on how often cron runs and how its jobs are staggered alongside segment and campaign jobs. Preparation often takes longer than the load itself: exporting from the old tool, normalizing encoding and dates, deciding tag structure and agreeing a test sample. Ask for the planned phases and dependencies in the statement of work, and confirm the cron schedule on your server before booking a load window.
Can all our contacts be imported in one pass?
A single pass is possible for a small, clean file, but a full load is rarely the safest first step. Mautic expects UTF-8 CSV with defined boolean values, pipe-separated tags and ISO 8601 dates, and a file that breaks any of these rules can load partially or incorrectly. A pilot on a representative subset, including awkward cases such as accented names, multi-value tags, blank email addresses and old consent flags, exposes mapping errors before they reach every record. The pilot also gives a timing baseline for the full run. Once the pilot results are signed off, the full import can run in split files by cron. We recommend a pilot for any list where a failed run would take significant effort to undo, and we write the pilot's pass criteria into the scope.
What does our team need to provide for an import?
Three groups of input decide whether the import goes smoothly. First, named data owners who can explain what each column means, which system produced it and which value wins when two sources disagree. Second, consent decisions: for each list, your organization must state whether contacts may receive marketing email, how the do-not-email flag should be set for opted-out or unknown records, and what evidence of consent exists in the old tool. DeployOpen can map those decisions into the file, but it cannot make them for you. Third, a named approver who accepts the pilot results and the final reconciliation counts before the production load. Also provide a complete export from the previous tool, administrator access to the Mautic instance for the load window, and a test environment where possible.
Can our own team import contacts into Mautic themselves?
Yes, a team with administrator access and someone comfortable with CSV files can load a small, clean list through the Mautic interface. The skills that take longer are data cleaning, duplicate reconciliation, deciding how custom fields and tags are structured, and running background imports on a server the team operates. The main risk is silent error rather than mechanics: a day-first date read in the wrong order, a boolean that marks everyone as opted out, or a tag that splits incorrectly can damage many records before anyone notices. Test your team against three questions. Has it run a background import on this server before? Can it reconcile counts against the source? Does it have a named owner for consent decisions? If any answer is no, a fixed-scope engagement with a pilot may cost less than repairing a damaged list.
Why do Mautic contact imports fail on encoding and dates?
Most failed or corrupted imports come from three causes: files that are not UTF-8 encoded, dates in local formats, and boolean values written in unexpected ways. A CSV saved from a spreadsheet in a legacy encoding can turn accented names into unreadable characters. Dates should follow ISO 8601 in the form year-month-day hours:minutes:seconds, so a day-first date may be read as the wrong day or rejected. For do-not-email and similar flags, Mautic accepts true, 1, on or yes, so other markers need converting before the load. Multiple tags must be separated with a pipe character, because a comma or semicolon creates a single odd tag. Engineers should also confirm that headers match custom field names if they expect automatic mapping, since mismatched headers leave data unmapped without an obvious error. Check a sample of every column before loading.
What happens to existing contacts during a re-import?
A re-import can update contacts that Mautic already holds, so matching rules and overwrite behavior must be decided before the load. Mautic offers an option to skip fields that already have a value on the contact. This protects data entered directly in Mautic or by a newer sync, but it also keeps a stale value when the source is more accurate. Decide field by field which source wins and record that decision in the mapping specification. Take a database backup before any production run so a wrong overwrite can be reversed. Test the re-import on a pilot subset that contains known contacts, then compare the counts of new, updated and unchanged records against expectations. Ask in the quote whether the reconciliation report is part of the agreed deliverables.
How should consent and opt-out flags be handled in an import?
Consent handling starts with a decision by your organization, and the import only carries that decision into Mautic. Map each opt-out or do-not-email status from the old tool to the matching Mautic flag, and treat a contact with no consent record as a case to decide, not as opted in. Where your policy requires it, keep the source list and the date of each consent state in a field or tag, formatted as ISO 8601 so audit questions can be answered from the data. The import does not make contacts compliant with GDPR or any other regime by itself. That depends on your lawful basis, notices and processes. DeployOpen prepares the mapping, controls and evidence for your assessment, while your legal and privacy teams set the position and independent auditors assess it.
How DeployOpen scopes, delivers and supports a Mautic contact migration
DeployOpen treats a contact import into Mautic as a scoped data project on infrastructure you control. We agree the source files, field map, tag and date rules and load method in writing before any data moves, then hand over a documented, repeatable import process your team can run again.
How we scope
- Inventory the source exports, their encodings, column headers and the contact fields each one carries.
- Agree a field map between source columns and Mautic contact fields, including how existing values are handled on overlap.
- Define tag, boolean and date conversion rules, plus the volume and batching approach, in a written scope before work starts.
How we build
- Convert exports to UTF-8 CSV, normalize booleans to accepted values and format dates as YYYY-MM-DD hh:mm:ss.
- Split large files and run background imports by cron, with a test import on a sample file in a non-production instance first.
- Verify counts, duplicates, tags and custom field values against the source after each run and record the results.
How we hand over
- Deliver the field map, conversion scripts, cron configuration and a step-by-step runbook for future imports.
- Document the reconciliation checks used, the error handling for rejected rows and who approves each load.
- Walk your marketing operations and platform team through a live import so they can repeat the process without us.
How we support
- Offer ongoing support and upgrades as a retainer if you need help with later imports or Mautic maintenance.
- Confirm with your team which Mautic release line you run, since the supported versions and their dates change over time.
- Agree in the written scope what post-handover support is included and how change requests are priced and scheduled.
