Using the Mautic API Library

Requirements

Installing the API Library

composer require mautic/api-library

HTTP Client

composer require guzzlehttp/guzzle:^7.3

<?php// Bootup the Composer autoloaderinclude__DIR__ .'/vendor/autoload.php';useGuzzleHttp\Client;useMautic\Auth\ApiAuth;// Initiate an HTTP Client$httpClient =newClient(['timeout'  =>10,]);// Initiate the auth object$initAuth =newApiAuth($httpClient);$auth     =$initAuth->newAuth($settings);// etc.

Mautic Setup

Authorization

Obtaining an access token

<?php// Bootup the Composer autoloaderinclude__DIR__ .'/vendor/autoload.php';useMautic\Auth\ApiAuth;session_start();$publicKey ='';$secretKey ='';$callback  ='';// ApiAuth->newAuth() will accept an array of Auth settings$settings = ['baseUrl'          =>'',// Base URL of the Mautic instance'version'          =>'OAuth2',// Version of the OAuth can be OAuth2 or OAuth1a. OAuth2 is the default value.'clientKey'        =>'',// Client/Consumer key from Mautic'clientSecret'     =>'',// Client/Consumer secret key from Mautic'callback'         =>'',// Redirect URI/Callback URI for this script];/*// If you already have the access token, et al, pass them in as well to prevent the need for reauthorization$settings['accessToken']        = $accessToken;$settings['accessTokenSecret']  = $accessTokenSecret; //for OAuth1.0a$settings['accessTokenExpires'] = $accessTokenExpires; //UNIX timestamp$settings['refreshToken']       = $refreshToken;*/// Initiate the auth object$initAuth =newApiAuth();$auth     =$initAuth->newAuth($settings);// Initiate process for obtaining an access token; this will redirect the user to the $authorizationUrl and/or// set the access_tokens when the user is redirected back after granting authorization// If the access token is expired, and a refresh token is set above, then a new access token will be requestedtry {if ($auth->validateAccessToken()) {// Obtain the access token returned; call accessTokenUpdated() to catch if the token was updated via a// refresh token// $accessTokenData will have the following keys:// For OAuth1.0a: access_token, access_token_secret, expires// For OAuth2: access_token, expires, token_type, refresh_tokenif ($auth->accessTokenUpdated()) {$accessTokenData =$auth->getAccessTokenData();//store access token data however you want        }    }}catch (Exception$e) {// Do Error handling}

Using Basic Authentication Instead

<?php// Bootup the Composer autoloaderinclude__DIR__ .'/vendor/autoload.php';useMautic\Auth\ApiAuth;session_start();// ApiAuth->newAuth() will accept an array of Auth settings$settings = ['userName'   =>'',// Create a new user'password'   =>'',// Make it a secure password];// Initiate the auth object specifying to use BasicAuth$initAuth =newApiAuth();$auth     =$initAuth->newAuth($settings,'BasicAuth');// Nothing else to do ... It's ready to use.// Just pass the auth object to the API context you are creating.

 ['errors' => [        ['code'    =>403,'message' =>'access_denied: OAuth2 authentication required','type'    =>'access_denied',        ],    ], ];

API Requests

Get a context object

<?phpuseMautic\MauticApi;// Create an api context by passing in the desired context (Contacts, Forms, Pages, etc), the $auth object from above// and the base URL to the Mautic server (i.e. http://my-mautic-server.com/api/)$api        =newMauticApi();$contactApi =$api->newApi('contacts',$auth,$apiUrl);

Retrieving items

<?php$response =$contactApi->get($id);$contact  =$response[$contactApi->itemName()];// getList accepts optional parameters for filtering, limiting, and ordering$response      =$contactApi->getList($filter,$start,$limit,$orderBy,$orderByDir);$totalContacts =$response['total'];$contact       =$response[$contactApi->listName()];

Creating an item

<?php$fields =$contactApi->getFieldList();$data =array();foreach ($fieldsas$field) {$data[$field['alias']] =$_POST[$field['alias']];}// Set the IP address the contact originated from if it is different than that of the server making the request$data['ipAddress'] =$ipAddress;// Create the contact$response =$contactApi->create($data);$contact  =$response[$contactApi->itemName()];

Editing an item

<?php$updatedData = ['firstname' =>'Updated Name'];$response =$contactApi->edit($contactId,$updatedData);$contact  =$response[$contactApi->itemName()];// If you want to create a new contact in the case that $contactId no longer exists// $response will be populated with the new contact item$response =$contactApi->edit($contactId,$updatedData,true);$contact  =$response[$contactApi->itemName()];

Deleting an item

<?php$response =$contactApi->delete($contactId);$contact  =$response[$contactApi->itemName()];

Error handling

<?php// $response returned by an API call should be checked for errors$response =$contactApi->delete($contactId);if (isset($response['errors'])) {foreach ($response['errors']as$error) {echo$error['code'] .":" .$error['message'];    }}

Contributing

Setting up your environment (automatically)

Setting up your environment (manually)

Unit tests

Contributors ✨