PHPackages                             themarketer/api-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. themarketer/api-client

ActiveLibrary[API Development](/categories/api)

themarketer/api-client
======================

The Marketer PHP api client

0.1.2(1mo ago)04MITPHPPHP ^8.1CI passing

Since Apr 28Pushed 1mo agoCompare

[ Source](https://github.com/the-marketer/api-client-php)[ Packagist](https://packagist.org/packages/themarketer/api-client)[ RSS](/packages/themarketer-api-client/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (2)Dependencies (10)Versions (5)Used By (0)

The Marketer API Client (PHP)
=============================

[](#the-marketer-api-client-php)

PHP client for the **The Marketer** API. It sends HTTP requests via **Guzzle** (the internal `ApiGateway` class) and validates payloads with **Symfony Validator** (the `AbstractPayload` / `Data` DTOs from `TheMarketer\ApiClient\Common`).

Client documentation
--------------------

[](#client-documentation)

For a structured, easy-to-follow version:

- [API Client Docs](https://the-marketer.github.io/api-client-php/docs/intro)

### Docusaurus site (GitHub Pages)

[](#docusaurus-site-github-pages)

The documentation is also available as a Docusaurus site in the `website/` folder.

Run locally:

```
cd website
npm install
npm run start
```

Deployment to GitHub Pages is configured through the workflow:

- `.github/workflows/deploy-docs.yml`

Requirements
------------

[](#requirements)

RequirementVersion / note**PHP**`^8.1`**Composer**for installing dependencies**ext-mbstring**required**Main dependencies**`guzzlehttp/guzzle` ^7, `symfony/validator` ^7, `symfony/expression-language` ^8**Development / tests**`phpunit` ^10, `orchestra/testbench` ^8 (for the test suite)Install in your project:

```
composer install
```

Public package (example):

```
composer require themarketer/api-client
```

---

Architecture at a glance
------------------------

[](#architecture-at-a-glance)

- **`TheMarketer\ApiClient\Client`** — single entry point: takes a configuration **array** (`customerId`, `restKey`, optionally `trackingKey`, `restUrl`, `trackingUrl`, `maxRetryAttempts`), builds **`Config`** + **`ApiContext`** and exposes the API modules (`subscribers()`, `orders()`, `checkCredentials()`, etc.).
- **`ApiContext`** — provides the **REST** gateway (`ApiGateway`) and the **tracking** gateway (`TrackingGateway`); both use Guzzle (configurable retry).
- **`ApiGateway`** — for REST: `k` (rest key) and `u` (customer id) query params; JSON on POST where the DTO requires it; maps HTTP errors to exceptions.
- **`TrackingGateway`** — for the tracking host: requires `trackingKey` in the config; a different set of authentication parameters in the query.
- **The classes in `src/Api/`** — encapsulate the endpoints; input validation happens in **`src/DTO/`**.

The base URL for REST is `Config::baseRestUrl()` = `{restUrl}/api/{apiVersion}/` (default `apiVersion` = `v1`). The default URLs live in `Client` / `Config` (`src/Common/Config.php`).

---

Basic usage
-----------

[](#basic-usage)

```
use TheMarketer\ApiClient\Client;

$client = new Client([
    'customerId' => 'THE_MARKETER_ACCOUNT_ID', // query `u` on REST
    'restKey' => 'REST_KEY',                    // query `k` on REST
    'trackingKey' => 'TRACKING_KEY',            // optional: for tracking events
    'maxRetryAttempts' => 1,                     // optional
]);

// Examples of accessing the grouped APIs
$client->subscribers()->addSubscriber([/* … */]);
$client->orders()->saveOrder([/* … */]);
$client->transactionals()->sendEmail([/* … */]);
```

---

Credentials and utilities (directly on `Client`)
------------------------------------------------

[](#credentials-and-utilities-directly-on-client)

These methods do not go through `subscribers()` / `orders()`; they are delegated to the internal **`CredentialsClient`**.

### `checkCredentials(string $trackingKey): bool`

[](#checkcredentialsstring-trackingkey-bool)

Checks the credentials (tracking key in the **JSON body** on REST, see `CredentialsClient`). On **`Client`**, it returns **`true`** if the decoded response is an empty array `[]`, otherwise **`false`**. For the raw JSON as an `array`, use `CredentialsClient::checkCredentials()` with the same context.

```
$ok = $client->checkCredentials('TRACKING_KEY');
```

### `checkApiCredentials(): bool`

[](#checkapicredentials-bool)

On **`Client`**, it returns a **`bool`** (same criterion: JSON body → empty array = success). For the full decoded response, see `CredentialsClient::checkApiCredentials()`.

```
$ok = $client->checkApiCredentials();
```

### `getCosts()`, `getRealtimeVisitors()`, `getSmsCredit(): array`

[](#getcosts-getrealtimevisitors-getsmscredit-array)

Decoded JSON response.

### `getReferralLink(?string $email = null): string`

[](#getreferrallinkstring-email--null-string)

Returns the **raw content** of the response (not JSON).

### `getDeliveryLogs(array $payload): array`

[](#getdeliverylogsarray-payload-array)

`email` required; optional: `per_page`, `page`, `start`, `end`.

### `getEnteredAutomation(array $payload): array`

[](#getenteredautomationarray-payload-array)

`date` required (`Y-m-d`); optional `page`, `perPage`.

### `config(): Config`

[](#config-config)

Access to `customerId`, `restKey`, `baseRestUrl()`, `trackingKey()`, etc.

---

API modules (examples)
----------------------

[](#api-modules-examples)

Accessor on `Client`Role`subscribers()`Subscribers: status, add/remove, bulk, tags, etc.`orders()`Orders, feed URL, retail, statistics`transactionals()`Transactional email and SMS`products()`Product CRUD / sync, categories, brands`campaigns()`List, create campaign, email report, last campaign`loyalty()`Loyalty points`coupons()`Available coupons, saving`reviews()`Product and merchant reviews, Merchant Pro settings`mobilePush()`Mobile push (iOS/Android tokens)`events()`Custom events`reports()`Email/SMS/push/forms/audience reportsDetails about parameters: the files in `src/Api/*Api.php` and `src/DTO/**`. The tests in `tests/*ApiTest.php` show examples of valid payloads.

### Campaigns — important notes

[](#campaigns--important-notes)

- **`list()`** uses **POST** to `/campaigns/list`, with the body from `ListCampaign`.
- **`create()`** requires a nested structure validated by `CreateCampaign`; for the **sender** it uses the keys **`name`**, **`sender`** (email), **`reply_to`** (not `sender_name` / `sender_email`).

### Reviews

[](#reviews)

- **`getProductReviews()`** returns a **string** (raw response content, not an automatically decoded `array`).

### Reports

[](#reports)

- Queries usually include `start`, `end`, `type` (see the enums in `src/Enum/` and the DTOs in `src/DTO/Reports/`).

---

Errors and exceptions
---------------------

[](#errors-and-exceptions)

**Before the request (local validation)**

- **`TheMarketer\ApiClient\Exception\ValidationException`** — missing `customerId` / `restKey` in the config, or messages from Symfony validation on the DTO.
- Missing required arguments when building a DTO can lead to **`ArgumentCountError`** or **`TypeError`** before any network call.

**After the request** (`ApiGateway` maps the HTTP status)

StatusException**401**`UnauthorizedException`**404**`CustomerNotFoundException`**405**`MethodNotAllowedException`Other errors`ApiException` (uses the code and message from the response; the message is extracted from the JSON `message` when present)On a successful response with invalid JSON, the methods that decode it can throw **`JsonException`**. For network errors: **`GuzzleHttp\Exception\GuzzleException`**.

---

Tests
-----

[](#tests)

```
composer test
```

The suite uses `ApiGateway` with a **Guzzle MockHandler** (no real API calls). For **`Client`** in tests with an HTTP mock, `context` is `readonly`; in practice `CredentialsClient` and the `*Api` classes are tested with the same stack — see `tests/CredentialsClientTest.php` and `tests/TestCase.php`.

---

Smoke script (`smoke.php`)
--------------------------

[](#smoke-script-smokephp)

A quick check with **real credentials** (do not commit keys to the repo):

```
php smoke.php
```

The example in the repo calls `checkCredentials($trackingKey)` — replace the values with the ones from your The Marketer account.

---

License
-------

[](#license)

MIT (see `composer.json`).

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance94

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~27 days

Total

3

Last Release

32d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/56d28ba81bf83f27f15d64332c55c5f25004aead889cf62658f982820e4cc44c?d=identicon)[themarketer](/maintainers/themarketer)

---

Top Contributors

[![radudalbea-mkt](https://avatars.githubusercontent.com/u/246182343?v=4)](https://github.com/radudalbea-mkt "radudalbea-mkt (19 commits)")[![negura-alexandru](https://avatars.githubusercontent.com/u/263327552?v=4)](https://github.com/negura-alexandru "negura-alexandru (16 commits)")[![cristiantoma-mkt](https://avatars.githubusercontent.com/u/275912144?v=4)](https://github.com/cristiantoma-mkt "cristiantoma-mkt (4 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/themarketer-api-client/health.svg)

```
[![Health](https://phpackages.com/badges/themarketer-api-client/health.svg)](https://phpackages.com/packages/themarketer-api-client)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.9M754](/packages/sylius-sylius)[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1189.8k](/packages/rcsofttech-audit-trail-bundle)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.8M511](/packages/pimcore-pimcore)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

9421.6k64](/packages/open-dxp-opendxp)[oro/platform

Business Application Platform (BAP)

645143.5k116](/packages/oro-platform)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)