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

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!

Article Number: 49
Author: Mar 14, 2023
Last Updated: Mar 14, 2023
Author: Ruth Cheesley [[email protected]]

Online URL: