Importing Campaigns

The import feature allows you to add pre-configured Campaigns to your Mautic instance using ZIP files that contain all the relevant data needed to construct a Campaign.

Importing a Campaign

You can import a Campaign in three ways.

1.Using Mautic instance

Click on the Campaigns menu to view existing Campaigns.
Click the Options button that resembles a cog icon in the top-right corner.
Select Import from the dropdown menu.
Choose the Campaign ZIP file* you wish to import, then click the Upload button.

Tip

* Use a ZIP file created from the Mautic export function - recommended. This ensures inclusion of Campaign data, external Assets, and Dynamic Content.
Select Actions option from the dropdown menu for the Campaign and Segment entities. Choose either Update entity or Create new entity.

These options appear when the import process detects existing Campaigns or Segments that match the imported data.

Click the Proceed button.

Once the import is successful, you should see a success notification.

Important

The Mautic instance only supports importing ZIP files. You can use both the command line and API endpoints to import correctly structured JSON files.

Activating an imported Campaign

Follow the steps below to activate an imported Campaign:

Click on the Campaigns menu.
Locate the newly imported Campaign.
Click the red toggle button next to the Campaign’s name to change the status to active.
Click Yes when a prompt message appears.

Activating a Campaign starts execution immediately. Review all Campaign steps, configurations, and associated Assets thoroughly before turning on a Campaign to prevent unintended execution of events.

When a Campaign goes live, scheduled events with relative delays follow the Campaign Republish Behavior configuration. If the Campaign uses a specific setting instead of the global default, the execution behavior changes:
- Use global setting - Applies the default behavior configured in the global Mautic settings.
- Restart on republish - Resets the delay timer completely. The delay period starts over from zero the moment the Campaign becomes active.
- Count delay only while published - Pauses the delay timer while the Campaign is inactive. The timer resumes from where it paused once the Campaign becomes active again.
- Count delay regardless of publish state - default option. Keeps the delay timer running continuously in the background, even while the Campaign remains inactive.
The toggle button automatically changes to green, indicating that the Campaign is active.

2.Using the command line

You can import Campaigns using the command line:

bin/console mautic:entity:import \
--entity=campaign \
--file=/tmp/entity_data.zip \
--user=<user_id>

Command parameters

--entity=campaign: specifies the type of entity to import, in this case, campaign.
--file=/tmp/entity_data.zip: the path to the ZIP file containing the Campaign data.
--user=<user_id>: the ID of the User performing the import.

Important

Ensure the ZIP file is a valid Mautic Campaign export
The specified User must have appropriate import permissions
Verify the path is correct before running the command

3.Using Mautic API

You can import Campaigns programmatically using the Mautic API.

cURL example with ZIP file

curl -X POST 'https://example.com/api/campaigns/import' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@/path/to/campaign_export.zip'

Python example with JSON data

import requests
import json

# API Endpoint
url = 'https://example.com/api/campaigns/import'

# Authentication
headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

# Body must be the full campaign export structure (same as entity_data.json)
with open('entity_data.json') as f:
    payload = json.load(f)
}

# Send import request
response = requests.post(url, headers=headers, json=payload)

# Handle response
if response.status_code == 201:
    print("Campaign imported successfully")

API import methods

Mautic supports two primary methods of API-based Campaign import:

ZIP file import
- Use multipart/form-data content type
- Upload the complete Campaign export ZIP file
- Includes all Campaign Assets and dependencies from the ZIP file
JSON data import
- Use application/json content type
- Send Campaign details directly in the request body
- Useful for creating new Campaigns or updating existing Campaigns

Important

Replace example.com with your actual Mautic instance domain.
Ensure you have a valid access token by accessing the API Credentials section within Mautic’s settings.
The imported Campaign must comply with Mautic’s Campaign structure.
Verify import permissions and data integrity.

How Campaign import works

During the import process, Mautic performs a comprehensive analysis of the data:

Permissions: verifies that the logged-in User has the correct permissions to import.
Entities: identifies required entities for the Campaign to function.
Plugin validation: the import function verifies Plugin installation. It evaluates if a Campaign template depends on an external Plugin. If a required Plugin is missing, the import process halts and prompts the User to install the necessary Plugin before continuing.
Conflict resolution: validates for potential ID conflicts in imported entities. Where conflicts exist, Mautic provides options to:
- Update existing entities, allowing Administrators to update existing Campaigns.
- Create new entities using a new ID.
Automatic data mapping: the system maps imported data to the correct locations and automatically creates any necessary dependent entities.
Campaign activation: after a successful import, the Campaign remains inactive by default.