Skip to Content

How to import contacts to Mautic in the background without timing out

Estimated Reading Time: 1 Minutes

Mautic users often need to import large numbers of contacts, usually in a .csv file.

Depending on the specifications of your server, there will come a limit where importing in the browser will fail, and you will end up with an incomplete import.

For this reason, Mautic has the facility to import contacts in the background using, you guessed it, a cron job!

Here's how to do it:


  1. Prepare your file for importing and ensure you have any custom fields created before starting
  2. Go to Contacts and click the arrow to open the import facility

    Screenshot of import dropdown

  3. Select the file you prepared in part 1, and upload it
  4. Configure the field mapping, segment and tag additions and owner
  5. Click 'Import in the background'

  6. In the import history, you will see the import with the status of 'queued'

  7. Go to your terminal window where you have an SSH connection to your server, and run the cron job to trigger the import (or wait for it to run, if you have it scheduled.

    Background import cron job

    php /path/to/mautic/bin/console mautic:import

    Replace /path/to/mautic with the file path to your Mautic installation.
  8. Watch the import progress in the command line terminal

  9. When the job is complete you will see the import history change from queued to imported, and all the contacts should be in your Mautic instance - hurrah!
How to import contacts to Mautic in the background without timing out
  • There is an issue of having the contacts imported at first it was importing good now it is importing less to no importing and the issue that i can import all the contacts without background import and there is no specifics to it. In order to run it so we can be able to do a fast import PLEASE HELP

    • Hi Anas, please post at with an explanation of the problems you're experiencing, and the community will be able to help you with troubleshooting. Sounds like perhaps it's a server resourcing issue but the forums will be the best place to get help with this. Thanks!

  • How does the update works when importing data ? does Mautic updates contacts during import based on existing name or email ? Thanks

    • Hi Rabbi, when Mautic imports data, whether that be a company or contact, it will look to see if the data in the custom fields which have been marked as unique matches anything that already exists in the database. Where it finds a match, the data is merged. Any new or additional data from the import will be added to the profile. There are some fields which are specified unique from the start, for example, email address. You can also add your own fields if there are other fields which you need to have as unique identifiers.


  • Powered by PHPKB (Knowledge Base Software)