Implementing Mautic API

notes web development mautic marketing developer technology

Mautic has API to interact with other systems. There is PHP API library for faster intagration to PHP projects. The API requires oAuth (1a or 2) authentication. API calls are great for integration with your current system(s). You can simply create a lead or move a lead to a smart list when the lead does something in your app.

1. Install Mautic API library with Composer

API library is at Packegist. So simple composer require mautic/api-library @dev command will installation of the library to your project for you. Composer will also automatically include the library to your project. The @dev part can be removed when the library will have some stable release.

2. Install Mautic API library other way

If your project doesn't use Composer yet, you can either clone it from GitHub or download the ZIP package and copy the library folder to your project.

2.1 Install by git clone

  1. Go to your project folder where you want to place Mautic API library to be. For example:

cd /var/www/html/myproject

  1. Run git clone to this folder

git clone git@github.com:mautic/api-library.git . (the dot at the end means current folder)

2.2 Copy from ZIP package

  1. Download the library from https://github.com/mautic/api-library/archive/master.zip
  2. Extract the package to some temporary location.
  3. Copy the /lib folder to your project.

3 Authorization of your Mautic API application

To use API calls, your application has to be authorized in Mautic instance you want to connect with. Mautic supports OAuth1 and OAuth2. I'll focus to OAuth1 since it doesn't require HTTPS. If your application has some kind of administration, you'll need to add 3 text inputs and an Authorization button there.

3.1 Get Authorization keys in Mautic

You can create specific authorization API credentials for each connected application. To do that, go to your Mautic administration and follow these steps:

  1. Go to Mautic Configuration / API Settings and set 'API enabled' to 'Yes', leave 'API mode' to 'OAuth1'. Save changes.
  2. At the right-hand side menu where Configuration is should appear the new menu item 'API Credentials'. Hit it.
  3. Create new credential. Fill in 'Name' (name of your app for example) and Callback URL (URL where your app will be listening responses from Mautic). Save credentials.
  4. Mautic should generate 'Consumer Key' and 'Consumer Secret' key.

3.2 Create Authorization form

If you don't want to hard-code authorization details, create form with text inputs: Mautic Base URL, Consumer Key and Consumer Secret with Save & Authorize button. This form should not be accessible for public.

Note: You can test authorization and API requests in build-in API Tester. You can find it in the /apitester directory of Mautic API Library.

3.3 Handle Authorization request

If administrator of your app hits Save & Authorize button, this is how you can handle the request:

// @todo check if the request is sent from user with admin rights
// @todo check if Base URL, Consumer/Client Key and Consumer/Client secret are not empty

// @todo load this array from database or config file
$accessTokenData = array(
    'accessToken' => '',
    'accessTokenSecret' => '',
    'accessTokenExpires' => ''
);

// @todo Sanitize this URL. Make sure it starts with http/https and doesn't end with '/'
$mauticBaseUrl = $_POST['mauticBaseUrl'];

$settings = array(
    'baseUrl'           => $mauticBaseUrl,
    'clientKey'         => $_POST['clientKey'],
    'clientSecret'      => $_POST['clientSecret'],
    'callback'          => 'http://yourapp.com', // @todo Change this to your app callback. It should be the same as you entered when you were creating Mautic API credentials.
    'version'           => 'OAuth1a'
);

if (!empty($accessTokenData['accessToken']) && !empty($accessTokenData['accessTokenSecret'])) {
    $settings['accessToken']        = $accessTokenData['accessToken'] ;
    $settings['accessTokenSecret']  = $accessTokenData['accessTokenSecret'];
    $settings['accessTokenExpires'] = $accessTokenData['accessTokenExpires'];
}

$auth = \Mautic\Auth\ApiAuth::initiate($settings);

if ($auth->validateAccessToken()) {
    if ($auth->accessTokenUpdated()) {
        $accessTokenData = $auth->getAccessTokenData();
        // @todo Save $accessTokenData
        // @todo Display success authorization message
    } else {
        // @todo Display info message that this app is already authorized.
    }
} else {
    // @todo Display info message that the token is not valid.
}

The workflow is this:

  1. Admin user fills in the Access Keys and Mautic Base URL to the form.
  2. If $accessTokenData aren't known yet, $auth->validateAccessToken() will redirect user to Mautic where he can authorize the app.
  3. After user confirms authorization, Mautic will redirect him back (to the Callback URL) to your app.
  4. $auth->getAccessTokenData() will return $accessTokenData which you have to save.

Live examples of authorization can be found at:

4 API Calls

Finally the fun part. I suppose the most used API call will be to create new lead in Mautic. For example if a visitor submits a form in your app. Here is an example:

($auth and $mauticBaseUrl are the same as from the code above. It would be clever to add those to methods to have them accessible from different places)

$leadApi    = \Mautic\MauticApi::getContext(
    "leads",
    $auth,
    $mauticBaseUrl . '/api/'
);

$lead = $leadApi->create(array(
    'ipAddress' => $_SERVER['REMOTE_ADDR'],
    'firstname' => $formData['firstname'],
    'lastname'  => $formData['lastname'],
    'email'     => $formData['email'],
));

There is much more you can do. All is described at API Library Documentation

Next Post Previous Post