Mautic API Library

https://github.com/mautic/api-library
Admin
A PHP library for connecting to and interacting with the Mautic API, supporting OAuth 1.0a, OAuth 2,...
Tokens:76,901
Snippets:569
Trust Score:10
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install the API Library with Composer

Source: https://github.com/mautic/api-library/blob/main/README.md

Use this command to install the Mautic API Library via Composer. Requires PHP 8.2 or newer and a PSR-18 HTTP Client, which can be installed simultaneously with guzzlehttp/guzzle:^7.3.

```bash
composer require mautic/api-library
```

--------------------------------

### Install Guzzle 7 HTTP Client

Source: https://github.com/mautic/api-library/blob/main/README.md

Install the Guzzle 7 HTTP client to provide the PSR-18 implementation required by the library. The client is auto-discovered via php-http/discovery.

```bash
composer require guzzlehttp/guzzle:^7.3
```

--------------------------------

### Example — download a theme

Source: https://github.com/mautic/api-library

Wraps a PSR-7 response, checks if it is a zip, and saves it to a directory. The result contains the absolute path to the downloaded file.

```php
use Mautic\Response;

// $psrResponse is a Psr\Http\Message\ResponseInterface from your HTTP client
$response = new Response($psrResponse);

if ($response->isZip()) {
    $result = $response->saveToFile('/tmp/mautic-downloads');
    // $result['file'] is the absolute path to the downloaded zip
    echo 'Saved to ' . $result['file'];
}
```

--------------------------------

### Retrieve items with get and getList

Source: https://github.com/mautic/api-library/blob/main/README.md

Shows how to fetch a single item by ID using get() and a list of items using getList(), which accepts optional parameters for filtering, limiting, and ordering. The response contains the item(s) under the context's itemName() or listName() key.

```php
<?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()];
```

--------------------------------

### Start DDEV environment

Source: https://github.com/mautic/api-library/blob/main/README.md

Run this command to automatically set up the development environment using DDEV. It clones the Mautic repository, sets up a local instance, and connects the API library tests to it.

```bash
ddev start
```

--------------------------------

### BasicAuth Example

Source: https://github.com/mautic/api-library

Creates a BasicAuth authentication instance using ApiAuth. Incorrect credentials result in a 403 error response from the API.

```php
use Mautic\Auth\ApiAuth;

$auth = (new ApiAuth())->newAuth(
    ['userName' => 'apiuser', 'password' => 'secret'],
    'BasicAuth'
);

// Incorrect credentials return a 403 error response from the API
$response = $contactApi->getList();
if (isset($response['errors'])) {
    // e.g. code 403, 'access_denied: OAuth2 authentication required'
}
```

--------------------------------

### getList(string $search = '', int $start = 0, int $limit = 0, string $orderBy = '', string $orderByDir = 'ASC', bool $publishedOnly = false, bool $minimal = false): array|mixed

Source: https://github.com/mautic/api-library

Lists items. Sends `GET {endpoint}` with query params, omitting empty ones.

```APIDOC
## getList(string $search = '', int $start = 0, int $limit = 0, string $orderBy = '', string $orderByDir = 'ASC', bool $publishedOnly = false, bool $minimal = false): array|mixed

### Description
Lists items. Sends `GET {endpoint}` with query params, *omitting empty ones* (`array_filter`).

### Parameters
- **$search** (string) - Optional - Search filter string. Default: `''`.
- **$start** (int) - Optional - Starting offset. Default: `0`.
- **$limit** (int) - Optional - Number of results (0 = server default). Default: `0`.
- **$orderBy** (string) - Optional - Field to order by. Default: `''`.
- **$orderByDir** (string) - Optional - Order direction (`ASC`/`DESC`). Default: `'ASC'`.
- **$publishedOnly** (bool) - Optional - Only published items. Default: `false`.
- **$minimal** (bool) - Optional - Return minimal data. Default: `false`.

### Returns
- **array|mixed** - The response array.
```

--------------------------------

### Example of getOrder() return value

Source: https://github.com/mautic/api-library

Shows the structure of the order array returned by getOrder().

```php
[['col' => 'email', 'dir' => 'asc']]
```

--------------------------------

### OAuth settings array for newAuth()

Source: https://github.com/mautic/api-library

Full example settings array for OAuth::setup() via newAuth($settings). Keys map to OAuth::setup() parameters; version selects OAuth 1.0a or OAuth 2. baseUrl is required to derive token/authorize URLs. Optional pre-existing token fields skip reauthorization.

```php
$settings = [
    'baseUrl'           => 'https://my-mautic-server.com',
    'version'           => 'OAuth2',
    'clientKey'         => 'client_key',
    'clientSecret'      => 'client_secret',
    'callback'          => 'https://app.example.com/callback',
    // optional pre-existing token
    'accessToken'       => $accessToken,
    'accessTokenExpires'=> $accessTokenExpires,  // UNIX timestamp
    'refreshToken'      => $refreshToken,
];
```

--------------------------------

### Example — creating and editing a contact via the base API

Source: https://github.com/mautic/api-library

Example usage of the base API to create and edit a contact.

```APIDOC
## Example — creating and editing a contact via the base API

```php
use Mautic\MauticApi;

$api        = new MauticApi();
$contactApi = $api->newApi('contacts', $auth, 'https://host/api/');

// getList with filters
$response  = $contactApi->getList('email:test@example.com', 0, 50, 'id', 'DESC');
$total     = $response['total'];
$contacts  = $response['contacts'];

// edit, creating if it does not exist
$updated = $contactApi->edit($id, ['firstname' => 'Jane'], true);

// delete
$deleted = $contactApi->delete($id);
```
```

--------------------------------

### Custom HTTP client and debug mode example

Source: https://github.com/mautic/api-library

Shows how to instantiate ApiAuth with a custom Guzzle client, enable debug mode, and handle UnexpectedResponseFormatException. Uses OAuth2 strategy.

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

$httpClient = new Client(['timeout' => 10]);

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

$auth->enableDebugMode();

try {
    $response = $auth->makeRequest('https://host/api/contacts');
    var_dump($auth->getResponseHeaders());
    var_dump($auth->getResponse()->getStatusCode());
} catch (\Mautic\Exception\UnexpectedResponseFormatException $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Example — error handling

Source: https://github.com/mautic/api-library

Catches UnexpectedResponseFormatException when constructing Response or decoding the body. The exception message and the offending response are accessible.

```php
use Mautic\Response;
use Mautic\Exception\UnexpectedResponseFormatException;

try {
    $response = new Response($psrResponse);
    $data     = $response->getDecodedBody();
} catch (UnexpectedResponseFormatException $e) {
    // Non-200/201 status, HTML error page, or unparseable body
    echo $e->getMessage();
    // $e->getResponse() exposes the offending Response
}
```

--------------------------------

### Building a custom list query with QueryBuilder

Source: https://github.com/mautic/api-library

Example of using QueryBuilder to build a custom list query with select, order, and where clauses, then passing it to getCustomList().

```php
use Mautic\QueryBuilder\QueryBuilder;

$query = new QueryBuilder();
$query->addSelect('id');
$query->addSelect('email');
$query->addSelect('firstname');
$query->addOrder('id', 'desc');

$expr = $query->expr();                 // fresh WhereBuilder
$expr->eq('email', 'user@example.com');
$expr->like('firstname', 'Jane%');
$query->addWhere($expr);

$response = $contactApi->getCustomList($query, 0, 100);
```

--------------------------------

### makeRequest raw request example

Source: https://github.com/mautic/api-library

Shows a raw request to the contacts endpoint with a search filter. The response is the decoded array from the API.

```php
$response = $contactApi->makeRequest('contacts', ['search' => 'email:test@example.com'], 'GET');
```

--------------------------------

### Composite WHERE with OR example

Source: https://github.com/mautic/api-library

Builds a composite WHERE clause using orX and andX builders, then adds them to an outer builder. The comment shows the resulting getClauses() output structure.

```php
$outer = new WhereBuilder();

$jb  = new WhereBuilder('orX');
$jb->eq('email', 'a@example.com');
$jb->eq('email', 'b@example.com');

$inner = new WhereBuilder('andX');
$inner->gte('points', 100);
$inner->neq('firstname', '');

$outer->add($jb);
$outer->add($inner);

// getClauses() produces:
//   [['col'=>null,'expr'=>'orX','val'=>[...a@...],[...b@...]]],
//    ['col'=>null,'expr'=>'andX','val'=>[...]]]
```

--------------------------------

### OAuth2 configuration passed to newAuth

Source: https://github.com/mautic/api-library

Example of OAuth2 configuration for newAuth. The settings array includes baseUrl, version, clientKey, clientSecret, callback, and optional accessToken, accessTokenSecret (OAuth1a only), accessTokenExpires, and refreshToken. The default authMethod is 'OAuth'.

```php
$settings = [
    'baseUrl'          => 'https://my-mautic-server.com',
    'version'          => 'OAuth2',      // 'OAuth1a' also allowed
    'clientKey'        => 'consumer_key',
    'clientSecret'     => 'consumer_secret',
    'callback'         => 'https://app.example.com/callback',
    'accessToken'      => $existingToken,     // optional
    'accessTokenSecret'=> '',                 // OAuth1a only
    'accessTokenExpires'=> $expiresUnixTs,    // optional
    'refreshToken'     => $refreshToken,      // optional
];

$auth = (new ApiAuth())->newAuth($settings);   // default method 'OAuth'
```

--------------------------------

### get(int $id): array|mixed

Source: https://github.com/mautic/api-library

Fetches a single item by ID.

```APIDOC
## get(int $id): array|mixed

### Description
Fetches a single item: `GET {baseUrl}{endpoint}/{id}`.

### Parameters
- **$id** (int) - Required - Item ID.

### Returns
- **array|mixed** - The response array.
```

--------------------------------

### ApiAuth::newAuth

Source: https://github.com/mautic/api-library

Builds an auth object based on the specified auth method. The class name is constructed as `Mautic\Auth\{$authMethod}` and its `setup()` method is invoked via reflection with the provided parameters.

```APIDOC
## ApiAuth::newAuth

### Description
Builds an auth object based on the specified auth method. The class name is constructed as `Mautic\Auth\{$authMethod}` and its `setup()` method is invoked via reflection with the provided parameters.

### Method
newAuth

### Signature
`newAuth(array $parameters = [], string $authMethod = 'OAuth'): AuthInterface`

### Parameters
- **$parameters** (array) - Optional - Associative array of parameters to pass to the auth object's `setup()` method.
- **$authMethod** (string) - Optional - Auth method name. Defaults to `'OAuth'` which maps to `Mautic\Auth\OAuth` (handles both OAuth1a and OAuth2 based on `version`). Other values like `'BasicAuth'` map to `Mautic\Auth\BasicAuth`.

### Return Value
- **AuthInterface** - The constructed auth object.

### Example — creating a BasicAuth object

```php
use Mautic\Auth\ApiAuth;

$settings = [
    'userName' => 'apiuser',
    'password' => 'aLongPassPhrase',
];

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

if ($auth->isAuthorized()) {
    // ready to use
}
```

### Example — OAuth2 configuration passed to `newAuth`

```php
$settings = [
    'baseUrl'          => 'https://my-mautic-server.com',
    'version'          => 'OAuth2',      // 'OAuth1a' also allowed
    'clientKey'        => 'consumer_key',
    'clientSecret'     => 'consumer_secret',
    'callback'         => 'https://app.example.com/callback',
    'accessToken'      => $existingToken,     // optional
    'accessTokenSecret'=> '',                 // OAuth1a only
    'accessTokenExpires'=> $expiresUnixTs,    // optional
    'refreshToken'     => $refreshToken,      // optional
];

$auth = (new ApiAuth())->newAuth($settings);   // default method 'OAuth'
```
```

--------------------------------

### getCustom(int $id, array $select = []): array|bool

Source: https://github.com/mautic/api-library

Fetches a single item with a `select` parameter (field projection). Returns `true` if the `get` endpoint is not supported, otherwise the response array.

```APIDOC
## getCustom(int $id, array $select = []): array|bool

### Description
Fetches a single item with a `select` parameter (field projection). Returns `true` if the `get` endpoint is not supported, otherwise the response array.

### Parameters
- **$id** (int) - Required - Item ID.
- **$select** (array) - Optional - Field projection.

### Returns
- **array|bool** - The response array, or `true` if the `get` endpoint is not supported.
```

--------------------------------

### makeRequest(string $endpoint, array $parameters = [], string $method = 'GET'): array

Source: https://github.com/mautic/api-library

The core request dispatcher. Calls $this->auth->makeRequest($url, $parameters, $method, $settings) and returns the decoded response.

```APIDOC
## makeRequest(string $endpoint, array $parameters = [], string $method = 'GET'): array

### Description
The core request dispatcher. Calls `$this->auth->makeRequest($url, $parameters, $method, $settings)` and returns the decoded response.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
#### Path Parameters
- `$endpoint` (string) - Required - Endpoint path relative to the base URL, or a full URL (if it contains `http`).

#### Query Parameters
- `$parameters` (array) - Optional - Query / body parameters. Default: `[]`.
- `$method` (string) - Optional - HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Default: `'GET'`.

### Response
#### Success Response
- **array** - The decoded response array.

#### Error Response
- If the final URL does not contain `http`, returns `['errors' => [['code' => 500, 'message' => 'URL is incomplete...']]]`.
- On a thrown `\Exception` from the HTTP/auth call, returns `['errors' => [['code' => $e->getCode(), 'message' => $e->getMessage()]]]`.
- If the auth layer returns a non-array, it is treated as an error: `['errors' => [['code' => 500, 'message' => $response]]]` and a warning is logged.
- Otherwise returns the decoded response array. Response errors are logged (as `error`) and each error entry is given a `code` from the HTTP status code if missing.

### Request Example
```php
$response = $contactApi->makeRequest('contacts', ['search' => 'email:test@example.com'], 'GET');
```
```

--------------------------------

### Check errors from API response

Source: https://github.com/mautic/api-library

Use this snippet to inspect an API response for errors after a delete call. Errors are returned inline in responses, not thrown, except where noted. The example prints the error code and message, e.g., '403: access_denied'.

```php
$response = $contactApi->delete($id);

if (isset($response['errors'])) {
    foreach ($response['errors'] as $error) {
        echo $error['code'] . ': ' . $error['message'];   // e.g. "403: access_denied"
    }
}
```

--------------------------------

### getActivityForContact(int $id, string $search = '', array $includeEvents = [], array $excludeEvents = [], string $orderBy = '', string $orderByDir = 'ASC', int $page = 1, ?\DateTime $dateFrom = null, ?\DateTime $dateTo = null)

Source: https://github.com/mautic/api-library

Returns contact activity for a specific contact: `GET contacts/{id}/activity`. Delegates to the protected `fetchActivity()`.

```APIDOC
## getActivityForContact(int $id, string $search = '', array $includeEvents = [], array $excludeEvents = [], string $orderBy = '', string $orderByDir = 'ASC', int $page = 1, ?\DateTime $dateFrom = null, ?\DateTime $dateTo = null)

### Description
Returns contact activity for a specific contact: `GET contacts/{id}/activity`. Delegates to the protected `fetchActivity()`.

### Returns
`array|mixed`.

### Query Parameters Sent
- `filters[search]`
- `filters[includeEvents]`
- `filters[excludeEvents]`
- `filters[dateFrom]` (formatted `Y-m-d H:i:s`)
- `filters[dateTo]`
- `order[]`
- `page`
```

--------------------------------

### BasicAuth::setup(string $userName, string $password)

Source: https://github.com/mautic/api-library

Configures basic authentication for the Mautic API client. Requires a valid username and password, throwing an exception if either is missing or empty.

```APIDOC
## BasicAuth::setup(string $userName, string $password)

### Description
Configures basic authentication for the Mautic API client. Requires a valid username and password, throwing an exception if either is missing or empty.

### Method
setup

### Parameters
#### Parameters
- **userName** (string) - Required - API login identifier (also settable as `username`). Missing/empty throws `RequiredParameterMissingException`.
- **password** (string) - Required - Password/passphrase. Missing/empty throws.

```

--------------------------------

### OAuth::setup(...) settings array

Source: https://github.com/mautic/api-library

Configures OAuth authentication for the Mautic API client. The `$parameters` array passed to `newAuth($settings)` maps onto `OAuth::setup()`; keys are matched to parameter names. `version` selects OAuth 1.0a vs OAuth 2.

```APIDOC
## OAuth::setup(...) settings array

### Description
Configures OAuth authentication for the Mautic API client. The `$parameters` array passed to `newAuth($settings)` maps onto `OAuth::setup()`; keys are matched to parameter names. `version` selects OAuth 1.0a vs OAuth 2.

### Method
setup

### Parameters
#### Parameters
- **baseUrl** (string) - Required* - Base URL of the Mautic instance (e.g. `https://host`). When set, token/authorize URLs are derived (`/oauth/v1/...` for OAuth1a, `/oauth/v2/...` for OAuth2).
- **version** (string) - Optional - `'OAuth2'` (default) or `'OAuth1a'`.
- **clientKey** (string) - Required* - Client/consumer key.
- **clientSecret** (string) - Required* - Client/consumer secret.
- **callback** (string) - Required* - Redirect/callback URI.
- **accessToken** (string) - Optional - Existing access token (skips reauthorization).
- **accessTokenSecret** (string) - Optional - OAuth1a access-token secret.
- **accessTokenExpires** (string) (unix ts) - Optional - When the token expires; used to trigger refresh.
- **refreshToken** (string) - Optional - OAuth2 refresh token, used to renew expired tokens.
- **scope** (string) - Optional - Comma-separated OAuth2 scope (converted to array).

\* Required to complete the OAuth handshake, though `setup()` accepts them as nullable and derives URLs when `baseUrl` is present.

### Request Example
```php
$settings = [
    'baseUrl'           => 'https://my-mautic-server.com',
    'version'           => 'OAuth2',
    'clientKey'         => 'client_key',
    'clientSecret'      => 'client_secret',
    'callback'          => 'https://app.example.com/callback',
    // optional pre-existing token
    'accessToken'       => $accessToken,
    'accessTokenExpires'=> $accessTokenExpires,  // UNIX timestamp
    'refreshToken'      => $refreshToken,
];
```

```

--------------------------------

### getSegments()

Source: https://github.com/mautic/api-library

Returns a list of contact segments: `GET contacts/list/segments`.

```APIDOC
## getSegments()

### Description
Returns a list of contact segments: `GET contacts/list/segments`.

### Returns
`array|mixed`.
```

--------------------------------

### Initialize HTTP Client and Auth

Source: https://github.com/mautic/api-library/blob/main/README.md

Boots the Composer autoloader, creates a Guzzle HTTP client with a 10-second timeout, and initializes the Mautic ApiAuth object. The $settings variable is expected to be defined elsewhere.

```php
<?php

// Bootup the Composer autoloader
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);
$auth     = $initAuth->newAuth($settings);
// etc.
```

--------------------------------

### getFieldList()

Source: https://github.com/mautic/api-library

Returns a list of custom contact fields: `GET contacts/list/fields`.

```APIDOC
## getFieldList()

### Description
Returns a list of custom contact fields: `GET contacts/list/fields`.

### Returns
`array|mixed`.
```

--------------------------------

### BasicAuth::setup

Source: https://github.com/mautic/api-library

Configures Basic HTTP authentication credentials. Both username and password must be non-empty after trimming, otherwise a RequiredParameterMissingException is thrown.

```APIDOC
## BasicAuth::setup

### Description
Configures Basic HTTP authentication credentials. Both username and password must be non-empty after trimming, otherwise a RequiredParameterMissingException is thrown.

### Method
setup

### Parameters
- `$userName` (string) - Required - API login identifier (username or email).
- `$password` (string) - Required - The password / passphrase.

### Throws
- `Mautic\Exception\RequiredParameterMissingException` - If either trimmed username or password is empty. Message: `"One or more required parameters was not supplied. Both userName and password required!"`

### Request Example
```php
use Mautic\Auth\ApiAuth;

$auth = (new ApiAuth())->newAuth(
    ['userName' => 'apiuser', 'password' => 'secret'],
    'BasicAuth'
);
```
```

--------------------------------

### getOwners()

Source: https://github.com/mautic/api-library

Returns a list of users available as contact owners: `GET contacts/list/owners`.

```APIDOC
## getOwners()

### Description
Returns a list of users available as contact owners: `GET contacts/list/owners`.

### Returns
`array|mixed`.
```

--------------------------------

### Themes::create

Source: https://github.com/mautic/api-library

Uploads a theme zip file to the Mautic API. Requires the 'file' parameter to be set, otherwise throws an exception.

```APIDOC
## Themes::create

### Description
Uploads a theme zip file to the Mautic API. Requires the 'file' parameter to be set, otherwise throws an exception.

### Method
- (SDK method)

### Parameters
#### Request Body
- **file** (string) - Required - The path to the theme zip file.

### Response
- No response schema specified.
```

--------------------------------

### Campaigns::getContacts

Source: https://github.com/mautic/api-library

Retrieves contacts associated with a campaign. This method overrides the base get method to support filtering and pagination.

```APIDOC
## GET campaigns/{id}/contacts

### Description
Retrieves contacts associated with a campaign. This method overrides the base get method to support filtering and pagination.

### Method
GET

### Endpoint
campaigns/{id}/contacts

### Parameters
#### Path Parameters
- **id** (int) - Required - The campaign ID.

#### Query Parameters
- **start** (int) - Optional - Starting record offset.
- **limit** (int) - Optional - Maximum number of records to return.
- **order** (array) - Optional - Ordering criteria.
- **where** (array) - Optional - Filtering criteria.

### Response
#### Success Response (200)
- List of contacts.
```

--------------------------------

### Run unit tests

Source: https://github.com/mautic/api-library/blob/main/README.md

Run all unit tests with Composer. The tests fire real API requests to a Mautic instance, so ensure the local environment is set up first.

```bash
composer test
```

--------------------------------

### OAuth::setup

Source: https://github.com/mautic/api-library

Configures the OAuth client. If a base URL is provided, derived token URLs are set based on the OAuth version. If an access token is provided, it is stored along with related details.

```APIDOC
## OAuth::setup

### Description
Configures the OAuth client. If a base URL is provided, derived token URLs are set based on the OAuth version. If an access token is provided, it is stored along with related details.

### Method
setup

### Parameters
- `$baseUrl` (string) - Optional - Default: `null` - Base URL of the Mautic instance (not including `/api/`).
- `$version` (string) - Optional - Default: `'OAuth2'` - `'OAuth2'` or `'OAuth1a'`.
- `$clientKey` (string) - Optional - Default: `null` - Client/consumer key.
- `$clientSecret` (string) - Optional - Default: `null` - Client/consumer secret.
- `$accessToken` (string) - Optional - Default: `null` - Existing access token.
- `$accessTokenSecret` (string) - Optional - Default: `null` - OAuth1a access token secret.
- `$accessTokenExpires` (string) - Optional - Default: `null` - UNIX timestamp of token expiry.
- `$callback` (string) - Optional - Default: `null` - Redirect/callback URI.
- `$scope` (string) - Optional - Default: `null` - Comma-separated OAuth2 scope.
- `$refreshToken` (string) - Optional - Default: `null` - OAuth2 refresh token.
```

--------------------------------

### Stats::get

Source: https://github.com/mautic/api-library

Retrieves statistics data from the Mautic API. This method overrides the base get method to support filtering and pagination.

```APIDOC
## GET stats[/{table}]

### Description
Retrieves statistics data from the Mautic API. This method overrides the base get method to support filtering and pagination.

### Method
GET

### Endpoint
stats[/{table}]

### Parameters
#### Path Parameters
- **table** (string) - Optional - The statistics table to retrieve.

#### Query Parameters
- **start** (int) - Optional - Starting record offset.
- **limit** (int) - Optional - Maximum number of records to return.
- **order** (array) - Optional - Ordering criteria.
- **where** (array) - Optional - Filtering criteria.

### Response
#### Success Response (200)
- Statistics data.
```

--------------------------------

### Themes::createBatch

Source: https://github.com/mautic/api-library

This operation is not supported and returns an actionNotSupported response.

```APIDOC
## Themes::createBatch

### Description
This operation is not supported and returns an actionNotSupported response.

### Method
- (SDK method)

### Parameters
- **parameters** (array) - Required - Batch parameters.

### Response
- Returns actionNotSupported(...).
```

--------------------------------

### ApiAuth::initiate

Source: https://github.com/mautic/api-library

Static, deprecated method that is equivalent to `(new self())->newAuth($parameters, $authMethod)`. Provided for backward compatibility.

```APIDOC
## ApiAuth::initiate

### Description
Static, deprecated method that is equivalent to `(new self())->newAuth($parameters, $authMethod)`. Provided for backward compatibility.

### Method
initiate (static)

### Signature
`public static function initiate($parameters = [], $authMethod = 'OAuth')`

### Parameters
- **$parameters** (array) - Optional - Associative array of parameters to pass to the auth object's `setup()` method.
- **$authMethod** (string) - Optional - Auth method name. Defaults to `'OAuth'`.

### Return Value
- **AuthInterface** - The constructed auth object.
```

--------------------------------

### Files::createBatch

Source: https://github.com/mautic/api-library

This operation is not supported and returns an actionNotSupported response.

```APIDOC
## Files::createBatch

### Description
This operation is not supported and returns an actionNotSupported response.

### Method
- (SDK method)

### Parameters
- **parameters** (array) - Required - Batch parameters.

### Response
- Returns actionNotSupported(...).
```

--------------------------------

### MauticApi::newApi(string $apiContext, AuthInterface $auth, string $baseUrl = '')

Source: https://github.com/mautic/api-library

Factory method to create a new API instance for a given context. It takes the API context name, an authentication object, and an optional base URL.

```APIDOC
## MauticApi::newApi(string $apiContext, AuthInterface $auth, string $baseUrl = '')

### Description
Factory method to create a new API instance for a given context. It takes the API context name, an authentication object, and an optional base URL.

### Parameters
- **$apiContext** (string) - Required - Context name, e.g. `contacts`.
- **$auth** (AuthInterface) - Required - Auth object.
- **$baseUrl** (string) - Optional - Default `''` - Base API URL, e.g. `https://host/api/` (auto-normalized by `Api::setBaseUrl()` — appends `/` and `api/`).
```

--------------------------------

### Debugging / session options

Source: https://github.com/mautic/api-library

Options for debugging and session handling. `enableDebugMode()` enables debug logging to the session, and `$bcTesting` is a public flag for unit testing.

```APIDOC
## Debugging / session options

### Description
Options for debugging and session handling. `enableDebugMode()` enables debug logging to the session, and `$bcTesting` is a public flag for unit testing.

### Methods

#### enableDebugMode()
- **Source**: `AbstractAuth::enableDebugMode()`
- **Description**: When enabled, debug info (status code, headers, body, request flow, tokens) is written to `$_SESSION['oauth']['debug']`; retrievable via `getDebugInfo()`. Requires a PHP session.

### Properties

#### $bcTesting
- **Source**: `Api::$bcTesting` (public)
- **Type**: mixed
- **Description**: Unit-test flag; when `true` or an array of method names, forces backward-compatible endpoint resolution during tests. Not intended for production.
```

--------------------------------

### Themes::getTemporaryFilepath

Source: https://github.com/mautic/api-library

Returns the configured temporary file path, or the system temp directory if not set.

```APIDOC
## Themes::getTemporaryFilepath

### Description
Returns the configured temporary file path, or the system temp directory if not set.

### Method
- (SDK method)

### Response
- Returns a string representing the temporary file path.
```

--------------------------------

### Creating a BasicAuth object with newAuth

Source: https://github.com/mautic/api-library

Shows how to create a BasicAuth object using the newAuth method. The settings array must include 'userName' and 'password'. After creation, check isAuthorized() before use.

```php
use Mautic\Auth\ApiAuth;

$settings = [
    'userName' => 'apiuser',
    'password' => 'aLongPassPhrase',
];

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

if ($auth->isAuthorized()) {
    // ready to use
}
```

--------------------------------

### Mautic\Api\Api::__construct(AuthInterface $auth, string $baseUrl = '')

Source: https://github.com/mautic/api-library

Constructor for the Api class. It accepts an authentication object and an optional base URL, with the same normalization behavior as the factory method.

```APIDOC
## Mautic\Api\Api::__construct(AuthInterface $auth, string $baseUrl = '')

### Description
Constructor for the Api class. It accepts an authentication object and an optional base URL, with the same normalization behavior as the factory method.

### Parameters
- **$auth** (AuthInterface) - Required - Auth object.
- **$baseUrl** (string) - Optional - Default `''` - Base API URL, e.g. `https://host/api/` (auto-normalized by `Api::setBaseUrl()` — appends `/` and `api/`).
```

--------------------------------

### Get a context object with MauticApi::newApi

Source: https://github.com/mautic/api-library/blob/main/README.md

Creates an API context (e.g., contacts) using the MauticApi class, the auth object, and the base API URL. The context object is required before making any API requests.

```php
<?php

use Mautic\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        = new MauticApi();
$contactApi = $api->newApi('contacts', $auth, $apiUrl);
```

--------------------------------

### Using deprecated getContext() static method

Source: https://github.com/mautic/api-library

Demonstrates the deprecated static getContext() method, which caches and reuses context instances.

```php
use Mautic\MauticApi;

$contactApi = MauticApi::getContext('contacts', $auth, $baseUrl);
```

--------------------------------

### Files::create

Source: https://github.com/mautic/api-library

Uploads a file to the Mautic API. Requires the 'file' parameter to be an existing file path, otherwise throws an exception.

```APIDOC
## Files::create

### Description
Uploads a file to the Mautic API. Requires the 'file' parameter to be an existing file path, otherwise throws an exception.

### Method
- POST

### Endpoint
`files/images/new` (or `files/{folder}/new` depending on the configured folder)

### Parameters
#### Request Body
- **file** (string) - Required - The path to the file to upload.

### Response
- No response schema specified.

### Request Example
```
POST files/images/new
Content-Type: multipart/form-data

file=@/path/to/file
```
```

--------------------------------

### getIdentified(string $search = '', int $start = 0, int $limit = 0, string $orderBy = '', string $orderByDir = 'ASC', bool $publishedOnly = false, bool $minimal = false)

Source: https://github.com/mautic/api-library

Returns only identified (non-anonymous) contacts. Prepends `!is:anonymous` to the search string and delegates to `getList()`.

```APIDOC
## getIdentified(string $search = '', int $start = 0, int $limit = 0, string $orderBy = '', string $orderByDir = 'ASC', bool $publishedOnly = false, bool $minimal = false)

### Description
Returns only identified (non-anonymous) contacts. Prepends `!is:anonymous` to the search string and delegates to `getList()`.

### Returns
`array|mixed` — the list response.
```

--------------------------------

### Create an item with create

Source: https://github.com/mautic/api-library/blob/main/README.md

Builds a data array from the contact field list, optionally sets the originating IP address, and creates a new contact. The response contains the created item under the context's itemName() key.

```php
<?php

$fields = $contactApi->getFieldList();

$data = array();

foreach ($fields as $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()];
```

--------------------------------

### getActivity(string $search = '', array $includeEvents = [], array $excludeEvents = [], string $orderBy = '', string $orderByDir = 'ASC', int $page = 1, ?\DateTime $dateFrom = null, ?\DateTime $dateTo = null)

Source: https://github.com/mautic/api-library

Returns contact engagement activity not tied to a specific contact: `GET contacts/activity`. Same parameter shape as above.

```APIDOC
## getActivity(string $search = '', array $includeEvents = [], array $excludeEvents = [], string $orderBy = '', string $orderByDir = 'ASC', int $page = 1, ?\DateTime $dateFrom = null, ?\DateTime $dateTo = null)

### Description
Returns contact engagement activity not tied to a specific contact: `GET contacts/activity`. Same parameter shape as above.

### Returns
`array|mixed`.
```

--------------------------------

### Data::create

Source: https://github.com/mautic/api-library

This operation is not supported and returns an actionNotSupported response.

```APIDOC
## Data::create

### Description
This operation is not supported and returns an actionNotSupported response.

### Method
- (SDK method)

### Parameters
- **parameters** (array) - Required - Parameters for creation.

### Response
- Returns actionNotSupported(__FUNCTION__).
```

--------------------------------

### Refresh an expired OAuth2 token

Source: https://github.com/mautic/api-library

Use this example to refresh an expired OAuth2 access token. It initializes ApiAuth with the stored access and refresh tokens, validates the access token, and if updated, retrieves the new token data to save for next time. Handles authorization required and incorrect parameters exceptions.

```php
use Mautic\Auth\ApiAuth;

$settings = [
    'baseUrl'      => 'https://host',
    'version'      => 'OAuth2',
    'clientKey'    => 'key',
    'clientSecret' => 'secret',
    'callback'     => 'https://app.example.com/callback',
    'accessToken'  => $accessToken,
    'refreshToken' => $refreshToken,
];

$auth = (new ApiAuth())->newAuth($settings);

try {
    if ($auth->validateAccessToken()) {
        if ($auth->accessTokenUpdated()) {
            $data = $auth->getAccessTokenData();
            // save $data['access_token'], $data['refresh_token'] for next time
        }
    }
} catch (\Mautic\Exception\AuthorizationRequiredException $e) {
    // redirect the user to $e->getAuthUrl() to grant authorization
} catch (\Mautic\Exception\IncorrectParametersReturnedException $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Filter contact activity by date range using getActivityForContact

Source: https://github.com/mautic/api-library

Use this PHP example to retrieve contact activity filtered by event types and a date range. The includeEvents and excludeEvents arrays control which events are returned; here only 'pageHit' events are included. The date range is set via DateTime objects for 2023-01-01 to 2023-12-31. Errors are returned inline in the 'errors' response key.

```php
use Mautic\Api\Contacts;

$response = $contactApi->getActivityForContact(
    $id,
    '',
    ['pageHit'],          // includeEvents
    [],                    // excludeEvents
    'dateHit',
    'DESC',
    1,
    new \DateTime('2023-01-01'),
    new \DateTime('2023-12-31')
);

if (isset($response['errors'])) {
    foreach ($response['errors'] as $error) {
        echo $error['code'] . ': ' . $error['message'];
    }
} else {
    // $response['events']... (server-defined shape)
}
```

--------------------------------

### Create, add points, retrieve contact

Source: https://github.com/mautic/api-library

Shows how to create a contact, add points and a DNC entry, then fetch the contact. Uses the MauticApi contacts API.

```php
use Mautic\MauticApi;

$api        = new MauticApi();
$contactApi = $api->newApi('contacts', $auth, $baseUrl);

// Create a contact
$fields = ['firstname' => 'Jane', 'lastname' => 'Doe', 'email' => 'jane@example.com'];
$response = $contactApi->create($fields);
$contact  = $response['contact'];
$id       = $contact['id'];

// Add points and a DNC reason
$contactApi->addPoints($id, 25, ['eventName' => 'signup', 'actionName' => 'form']);
$contactApi->addDnc($id, 'email', Contacts::MANUAL, null, 'Unsubscribed via API');

// Fetch the contact
$response = $contactApi->get($id);
```

--------------------------------

### Catch RequiredParameterMissingException from BasicAuth::setup()

Source: https://github.com/mautic/api-library

Catches the exception raised by BasicAuth::setup() when the username or password is empty after trimming. The actual message is "One or more required parameters was not supplied. Both userName and password required!".

```php
use Mautic\Exception\RequiredParameterMissingException;

try {
    $auth = (new ApiAuth())->newAuth(['userName' => ''], 'BasicAuth');
} catch (RequiredParameterMissingException $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Obtain an access token with OAuth2 or OAuth1.0a

Source: https://github.com/mautic/api-library/blob/main/README.md

Bootstraps the Composer autoloader, initializes the Mautic ApiAuth object with OAuth settings, and validates the access token. If the token is updated via a refresh token, the new token data is retrieved and can be stored. The settings array includes baseUrl, version (OAuth2 or OAuth1a), clientKey, clientSecret, and callback. Optional access token parameters can be passed to prevent reauthorization.

```php
<?php

// Bootup the Composer autoloader
include __DIR__ . '/vendor/autoload.php';  

use Mautic\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 = new ApiAuth();
$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 requested

try {
    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_token

        if ($auth->accessTokenUpdated()) {
            $accessTokenData = $auth->getAccessTokenData();

            //store access token data however you want
        }
    }
} catch (Exception $e) {
    // Do Error handling
}
```

--------------------------------

### Handling unknown context with newApi()

Source: https://github.com/mautic/api-library

Shows how to catch ContextNotFoundException when an invalid context name is passed to newApi().

```php
use Mautic\MauticApi;
use Mautic\Exception\ContextNotFoundException;

$api = new MauticApi();

try {
    $bogusApi = $api->newApi('not_a_real_context', $auth, $baseUrl);
} catch (ContextNotFoundException $e) {
    // "A context of 'Not_a_real_context' was not found."
    error_log($e->getMessage());
}
```

--------------------------------

### Creating and editing a contact via the base API

Source: https://github.com/mautic/api-library

Shows how to instantiate MauticApi, create a contacts API, call getList with filters, edit a contact (creating it if missing via the third parameter), and delete it.

```php
use Mautic\MauticApi;

$api        = new MauticApi();
$contactApi = $api->newApi('contacts', $auth, 'https://host/api/');

// getList with filters
$response  = $contactApi->getList('email:test@example.com', 0, 50, 'id', 'DESC');
$total     = $response['total'];
$contacts  = $response['contacts'];

// edit, creating if it does not exist
$updated = $contactApi->edit($id, ['firstname' => 'Jane'], true);

// delete
$deleted = $contactApi->delete($id);
```

--------------------------------

### Import Mautic\Response

Source: https://github.com/mautic/api-library

Import the Response class from the Mautic namespace.

```php
use Mautic\Response;
```
Tokens:
Raw