Contacts can be imported via the user interface from a CSV file. You can import from the browser or in the background via a cron job.
Background import is recommended.
Since Mautic 2.9, when an import job creates or updates a contact, you'll see that action in the Contact events history.
doNotEmail
or custom boolean field, use values true
, 1
, on
or yes
as TRUE value. Anything else will be considered false.YYYY-MM-DD hh:mm:ss
2019-01-02 19:08:42
. Other formats may work too, but they may be problematic.
firstname
, this field will be mapped automatically to {contactfield=firstname}
.ProTip
If using a Linux system, see the GNU parallel command. (sudo apt install parallel)
cat big_contact_list.csv | parallel --header : --pipe -N 1000 'cat > split_list_part{#}.csv'
This will generate files:
split_list_part1.csv ...split_list_part9.csv, split_list_part10.csv ...
Larger CSV files have to be imported in batches to avoid hitting server (PHP) memory and execution time limits. When importing in the browser, your browser is controlling the batches. When one finishes, the javascript starts a new one. This means the browser window has to stay opened and connected to the internet the whole time.
Use the browser import method only if you don't have any other choice. Background import is recommended.
Background import jobs (CLI command triggered manually or via a cron job) have the advantage of benevolent time limits. A CSV background import is not restarted every batch (1 batch = 100 rows by default) - the last row imported is saved, and the next batch continues from that point. Background imports will always be faster and more reliable than browser imports.
This option is available since Mautic 2.9.
Warning background import require the command
php /path/to/mautic/bin/console mautic:import
to run periodically. Add it to your cron jobs.
Successful result of the background job can look like this:
$ bin/console mautic:import
48/48 [============================] 100%
48 lines were processed, 0 items created, 48 items updated, 0 items ignored in 4.78 s
If there is no import waiting in the queue, there won't be any messages (or use --quiet
).
There is an option in the Global Mautic Configuration / Contact settings to define what is the optimal limit of browser import vs background import. If you enter 500
, that means that if the CSV file being imported has less than 500 rows, it will be imported in the browser. If it has more than 500 rows, it will be queued to be imported by the background job. Default value is 0 (zero), which means it will show two Import buttons instead of one and you have to decide what import option to use during every import.
The import can take several minutes. It's possible that one import will still run when the other will be started. To prevent running out of server resources, there is the parallel_import_limit
configurable option. By default only 1 import will run at the same time. This option can be changed when you add it to your app/config/local.php
file.
The list of imports can be found when you go to the Contacts area, open the action menu above the contacts table and choose the Import History option.
ProTip
The direct URL is
https://example.com/s/contacts/import/1
The table will show you:
There is also the toggle switch which will enable you to stop and startQueued or In Process imports.\ This type of switch is used throughout the Mautic UI to publish and unpublish items.
There are several potential statuses for import jobs:
Clicking on a filename opens the import job detail page.
The main content area displays information about rows which were ignored for some reason (if any). The table will tell you what row in the CSV file it was and what was the reason, so you can fix those rows and start the import again.
There are two charts:
More detailed statistics and the import job configuration are available if you click on Details. This includes import speed, field mappings, and job timestamps.
ProTip
The direct URL is
https://example.com/s/contacts/import/new
When the background job finishes, either successfully or if it fails, you'll get a notification in Mautic's notification area about it.
Q: My import times out. What can I do about that? A: Either use the background job to import or change the batch limit to smaller number than 100.
Q: If I import Do Not Contact values, is that stored as a bounce or a unsubscription? A: It is stored as a Manual Unsubscription. It is the same as if the Contact was marked as Do Not Contact from the Contacts page.
Found errors? Think you can improve this documentation? edit this page