Mautic API Library

Before using the library, you must enable the API in your Mautic instance:

1. Go to Settings > Configuration and enable Mautic's API.
2. If using Basic Authentication, ensure it is enabled in the same settings.
3. Go to Settings > API Credentials and create a new client.
4. Enter your application's callback/redirect URI.
5. Copy the generated Client ID and Client Secret for use in your application.

In version 4.0.0, the setCurlTimeout() method on the authentication object has been removed. To set a request timeout, you must now configure it directly on your PSR-18 compliant HTTP client during instantiation.

If you are using Guzzle 7, pass the timeout option into the client constructor.

$httpClient = new \GuzzleHttp\Client([
    'timeout'  => 10,
]);
$settings = [
    // ...
];

$initAuth = new \Mautic\Auth\ApiAuth($httpClient);
$auth = $initAuth->newAuth($settings);

Install the library using Composer. You must also install a PSR-18 compliant HTTP client (such as Guzzle) to ensure the library can make network requests.

composer require mautic/api-library guzzlehttp/guzzle:^7.3

The Mautic\Api\Contacts class provides methods to interact with contact data in Mautic. You can retrieve contact lists, manage contact points (scoring), handle 'Do Not Contact' (DNC) settings, and manage UTM tags.

Common tasks include:

• Retrieving lists of owners, custom fields, or segments.
• Fetching activity, notes, devices, or campaigns associated with a specific contact.
• Modifying contact scoring (points and point groups).
• Managing DNC status and UTM tags.

API responses may contain an errors key. Always check for this key to handle issues like authentication failures or invalid data.

<?php

$response = $contactApi->delete($contactId);

if (isset($response['errors'])) {
    foreach ($response['errors'] as $error) {
        echo $error['code'] . ": " . $error['message'];
    }
}

/* 
Example error structure:
[
    'errors' => [
        [
            'code'    => 403,
            'message' => 'access_denied: OAuth2 authentication required',
            'type'    => 'access_denied',
        ],
    ],
]
*/

For simpler setups, you can use Basic Authentication by providing a userName and password in the settings and specifying 'BasicAuth' as the second argument to newAuth().

<?php

include __DIR__ . '/vendor/autoload.php';  

use Mautic\Auth\ApiAuth;

session_start();

$settings = [
    'userName'   => '',             // Mautic username
    'password'   => '',             // Mautic password
];

$initAuth = new ApiAuth();
$auth     = $initAuth->newAuth($settings, 'BasicAuth');

The library is decoupled from specific HTTP implementations via the PSR-18 standard. You can provide your own client (e.g., Guzzle) to the ApiAuth constructor.

<?php

include __DIR__ . '/vendor/autoload.php';  

use GuzzleHttp\Client;
use Mautic\Auth\ApiAuth;

// Initiate an HTTP Client
$httpClient = new Client([
    'timeout'  => 10,
]);

// Initiate the auth object
$initAuth = new ApiAuth($httpClient);
// ...

To interact with specific Mautic resources (like Contacts, Forms, or Pages), create a context object using MauticApi::newApi().

<?php

use Mautic\MauticApi;

$api        = new MauticApi();
// $auth is the object obtained from ApiAuth
// $apiUrl is the base URL of your Mautic server (e.g., http://my-mautic-server.com/api/)
$contactApi = $api->newApi('contacts', $auth, $apiUrl);

Context objects provide methods to manage resource lifecycles:

• create($data): Creates a new item.
• edit($id, $data, $createIfMissing = false): Updates an existing item. If the third parameter is true, it will create the item if the ID is not found.
• delete($id): Removes an item.

<?php

// Create
$fields = $contactApi->getFieldList();
$data = [];
foreach ($fields as $field) {
    $data[$field['alias']] = $_POST[$field['alias']];
}
$data['ipAddress'] = $ipAddress;
$response = $contactApi->create($data);
$contact  = $response[$contactApi->itemName()];

// Edit
$updatedData = ['firstname' => 'Updated Name'];
$response = $contactApi->edit($contactId, $updatedData);
// To create if missing:
// $response = $contactApi->edit($contactId, $updatedData, true);

// Delete
$response = $contactApi->delete($contactId);