Themes

Use this endpoint to manipulate and obtain details on Mautic’s Themes.

Using the Mautic API library

You can interact with this API using the Mautic API Library as below, or the various HTTP endpoints described in this document.

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth  = new ApiAuth();
$auth      = $initAuth->newAuth($settings);
$apiUrl    = "https://example.com";
$api       = new MauticApi();
$themesApi = $api->newApi("themes", $auth, $apiUrl);

Get Theme

Retrieves the Theme as a ZIP file with the application/zip header on success, or a JSON response with error messages on failure. The PHP API library saves the ZIP file to the system’s temporary directory and retrieves the path.

<?php

//...
$response = $themesApi->get($themeName);

HTTP request

GET /themes/THEME_NAME

Response

• Returns 200 OK when the request successfully retrieves the Theme ZIP file.

{
    "file": "/absolute/path/to/the/system/temp/dir/with/the/theme/zip/file"
}

Set temporary file path

Changes the default temporary directory where the PHP API library creates the ZIP file. Creates the directory if it doesn’t exist.

<?php

//...
$themesApi->setTemporaryFilePath("/absolute/path/to/a/different/temp/dir");
$response = $themesApi->get($themeName);

Response

• Returns 200 OK when the request successfully changes or creates the default temporary directory.

{
    "file": "/absolute/path/to/a/different/temp/dir/zipfile"
}

List Themes

Lists all installed Themes with details from their config.json files.

<?php

//...
$response = $themesApi->getList();

HTTP request

GET /themes

Response

• Returns 200 OK when the request successfully retrieves the Themes list.

{
    "themes": {
        "blank": {
            "name": "Blank",
            "key": "blank",
            "config": {
                "name": "Blank",
                "author": "Mautic team",
                "authorUrl": "https://mautic.org",
                "features": [
                    "page",
                    "email",
                    "form"
                ]
            }
        }
    }
}

Properties

Name	Type	Description
themes	array	List of installed Themes and their configurations

Theme object properties

Name	Type	Description
name	string	Display name of the Theme
key	string	Directory name and unique identifier of the Theme
config	object	Theme configuration from config.json

Config object properties

Name	Type	Description
name	string	Theme name
author	string	Theme author
authorUrl	string	Author’s website URL
features	array	List of supported features such as page, email, or form
builder	array	Optional list of compatible builders such as legacy or grapeJs

Create Theme

Creates a new Theme or updates an existing one from the provided ZIP file. The Theme name comes from the ZIP filename.

<?php

//...
$data = array(
    'file' => dirname(__DIR__) . '/' . 'mytheme.zip'
);

$response = $themesApi->create($data);

Mautic sends the file through a standard POST files array, the same way a browser sends files during upload.

HTTP request

POST /themes/new

POST parameters

Name	Type	Description
file	file	The ZIP file containing the Theme - required

Response

• Returns 200 OK when the request successfully creates a Theme.

{
    "success": true
}

Error responses

The API returns error messages if:

• The request includes no uploaded file

• The uploaded file doesn’t have a .zip extension

• The ZIP file is missing required files - config.json and html/message.html.twig

• The ZIP file contains disallowed file extensions

Delete Theme

Deletes a Theme. The system prevents deletion of stock Themes.

<?php

//...
$response = $themesApi->delete($themeName);

HTTP request

DELETE /themes/THEME_NAME/delete

Response

• Returns 200 OK when the request successfully deletes the Theme.

{
    "success": true
}

Note

Mautic prevents permanent deletion of default Themes bundled with the app. Attempting to delete a default Theme hides it instead. Use the Theme visibility toggle in the Mautic UI to restore hidden default Themes.