Mautic API Library

Mautic API Library is the official PHP SDK for talking to a Mautic instance’s REST API. Instead of hand-building HTTP requests and OAuth flows against Mautic’s endpoints, PHP applications require this package, obtain an auth object (OAuth1a, OAuth2, or Basic Auth), and get a context object per resource (contacts, campaigns, forms, segments, points, reports, and roughly thirty others) that exposes a consistent get/getList/create/edit/delete/batch interface.

The library is decoupled from any specific HTTP transport through PSR-18, auto-discovering an available client (Guzzle by default) via php-http/discovery, and normalizes every response into a predictable array shape with error codes surfaced consistently rather than left to bubble up as uncaught exceptions. It backs both first-party Mautic integrations and third-party tools that automate marketing workflows against self-hosted or cloud Mautic instances.

What You Get

• A unified MauticApi::newApi() factory that returns a context object (Contacts, Campaigns, Forms, etc.) sharing the same get/getList/create/edit/delete/batch methods, so switching resources means changing one string, not learning a new API surface
• Pluggable authentication - BasicAuth, OAuth1a, and OAuth2 all implement the same AuthInterface, selected by a single string at setup with no other code changes required
• Transport-agnostic HTTP via PSR-18, auto-discovered through php-http/discovery so any compliant client (Guzzle by default) can be swapped in without touching library code
• A QueryBuilder/WhereBuilder DSL for constructing filtered, ordered custom-list queries against searchable Mautic endpoints
• Normalized error handling - failed requests return a consistent ['errors' => [...]] array with codes rather than requiring try/catch around every call
• PSR-3 logging support (NullLogger by default) so request/response activity can be wired into an application’s existing logger

Common Use Cases

• Syncing contacts, companies, and custom field data between a CRM or e-commerce platform and a Mautic instance
• Triggering and monitoring marketing campaigns, segments, and point-based lead scoring from an external application
• Building custom dashboards or reporting tools on top of Mautic’s Reports and Stats API contexts
• Automating form, email, and landing-page management as part of a broader marketing-ops pipeline
• Embedding Mautic authentication and API access inside another PHP application or plugin without duplicating OAuth handling

Under The Hood

Architecture The library follows a factory-plus-shared-base pattern: MauticApi::newApi() instantiates one of roughly thirty Mautic\Api\* context classes (Contacts, Campaigns, Forms, and so on), all extending a common Api base that centralizes makeRequest(), the get/getList/create/edit/delete/batch conventions, and legacy-endpoint fallback logic. Authentication is decoupled behind an AuthInterface implemented by BasicAuth and the substantial OAuth class (handling OAuth1a token exchange and refresh), both built on AbstractAuth wrapping a PSR-18 ClientInterface discovered via php-http/discovery - the library owns no HTTP transport of its own. Every request funnels through Api::makeRequest(), which normalizes responses via a Response object that validates JSON and raises typed exceptions from the Exception namespace, and a small QueryBuilder/WhereBuilder pair supplies a fluent DSL for the searchable list endpoints. Because context subclasses only override a handful of properties ($endpoint, $listName, $itemName, $endpointsSupported), the separation of concerns is consistent, though some deprecated static methods still coexist alongside the current API for backward compatibility.

Tech Stack Built for PHP 8.2+, decoupled from any concrete HTTP client via psr/http-client and psr/http-client-implementation, with auto-discovery through php-http/discovery and guzzlehttp/psr7 for PSR-7 message objects; psr/log provides optional logging with a NullLogger default. Dev tooling covers PHPUnit for tests, PHPStan (level 1) for static analysis, PHP-CS-Fixer for formatting, Rector for automated refactors, and Guzzle as the dev-time PSR-18 implementation. It has no framework dependency of its own - a standalone Composer library autoloaded via PSR-4 that either integration developers or the Mautic core project itself can require.

Code Quality The test suite includes one dedicated test class per API context (ContactsTest, CampaignsTest, and roughly thirty more) plus coverage for QueryBuilder, WhereBuilder, and Response, sharing a common MauticApiTestCase base. Rather than mocking, tests fire real requests against a live Mautic instance configured through a local config file, an integration-first approach wired into a GitHub Actions workflow. Naming is consistent PSR-4/PascalCase, error handling is explicit (failures are normalized into an errors array or raised as typed exceptions rather than swallowed), but most method signatures still rely on PHPDoc rather than native PHP type declarations, and PHPStan is configured at a permissive level.

API Design The library’s core ergonomic win is that every resource context exposes the identical CRUD verb set, so consumer code stays uniform regardless of which Mautic entity it’s touching, and auth method (Basic, OAuth1a, OAuth2) is chosen by a single string with no other code changes. The tradeoff is that responses are always raw associative arrays with no typed DTOs, so IDE autocomplete and type safety are minimal despite the PHP 8.2 baseline, and errors surface as an ['errors' => [...]] array in the common path rather than exceptions - callers must remember to check for it on every call, as the README’s own examples show. Documentation is thorough, with runnable examples for authentication, CRUD, and error handling covering onboarding well.