PHPackages                             xqueue/maileon-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. xqueue/maileon-api-client

ActiveLibrary[API Development](/categories/api)

xqueue/maileon-api-client
=========================

API-Client to XQ:Maileon

v1.25.1(1mo ago)5141.7k↓50%9[2 issues](https://github.com/xqueue/maileon-php-api-client/issues)[2 PRs](https://github.com/xqueue/maileon-php-api-client/pulls)3MITPHPPHP ^7.0|^8.0CI failing

Since Feb 28Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/xqueue/maileon-php-api-client)[ Packagist](https://packagist.org/packages/xqueue/maileon-api-client)[ Docs](https://www.maileon.de)[ RSS](/packages/xqueue-maileon-api-client/feed)WikiDiscussions master Synced yesterday

READMEChangelog (10)Dependencies (8)Versions (54)Used By (3)

[![Latest Version](https://camo.githubusercontent.com/e52c4a81ea59572d221ea6f8da58b1c8d7c59b253ccaace5edb9b353da945fdc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7871756575652f6d61696c656f6e2d6170692d636c69656e74)](https://packagist.org/packages/xqueue/maileon-api-client)[![License](https://camo.githubusercontent.com/eb61e158f0c9acaf6eb85f539b65309e87615279d21a40bca16fc95aa51f8ede/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7871756575652f6d61696c656f6e2d6170692d636c69656e74)](https://packagist.org/packages/xqueue/maileon-api-client)[![PHP Version Require](https://camo.githubusercontent.com/a15da40903e2f606debd878506b3a4de2bff29d96b7b83ad03242de187f216fb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f7871756575652f6d61696c656f6e2d6170692d636c69656e742f706870)](https://packagist.org/packages/xqueue/maileon-api-client)

Maileon API Client
==================

[](#maileon-api-client)

Provides an API client to connect to XQueue Maileon's REST API and (de-)serializes all API functions and data for easier use in PHP projects.

Maileon's REST API documentation can be found [here](https://maileon.com/support/rest-api-1-0/).

For runnable examples and integration tests see the [maileon-php-api-client-examples](https://github.com/xqueue/maileon-php-api-client-examples) repository.

Table of contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Response handling](#response-handling)
- [Examples](#examples)
    - [Contact examples](#contact-examples)
    - [Report example](#report-example)
    - [Mailing example](#mailing-example)
    - [Data Extensions examples](#data-extensions-examples)
    - [Transaction example](#transaction-example)

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

[](#requirements)

The API client requires `PHP >= 7.4` with `libxml` and `libcurl`.

Additionally, all requests use an SSL encrypted API endpoint. To enable SSL support in CURL, please follow these steps:

1. Download the official SSL cert bundle by CURL from
2. Save the bundle to a directory that can be accessed by your PHP installation
3. Add the following entry to your php.ini (remember to change the path to where you put the cert bundle):

```
curl.cainfo="your-path-to-the-bundle/cacert.pem"

```

Installation
------------

[](#installation)

You can add this library to your project using [Composer](https://getcomposer.org/):

```
composer require xqueue/maileon-api-client

```

Configuration
-------------

[](#configuration)

All services accept a configuration array as their constructor argument. The following keys are supported:

KeyRequiredDefaultDescription`API_KEY`yes—Your Maileon REST API key`BASE_URI`no`https://api.maileon.com/1.0`Override the API base URL (e.g. for staging)`DEBUG`no`false`Print cURL session logs and response details. **Do not enable in production** — output may contain sensitive data`THROW_EXCEPTION`no`true`Throw a `MaileonAPIException` on connection errors or 5xx responses. When `false`, those calls return `null` instead`TIMEOUT`no`5`cURL connect and total timeout in seconds`PROXY_HOST`no—Proxy hostname or IP`PROXY_PORT`no`80`Proxy port```
$service = new ContactsService([
    'API_KEY'         => 'Your API key',
    'TIMEOUT'         => 10,
    'THROW_EXCEPTION' => false,
]);
```

Usage
-----

[](#usage)

The API client divides the features of Maileon's REST API into specific consumable services. Each service provides all functions of its specific category.

The following services are available:

- **Contacts**Read, subscribe, edit, unsubscribe or delete contacts. Functions for individual contacts or bulk requests if required.
- **Blacklists**Manage your blacklists.
- **Contact filters**Segment your address pool by filter rules.
- **Targetgroups**Manage distribution lists to specify who gets which mailing.
- **Reports**Get all [KPI](https://kpi.org/KPI-Basics) information about your mailings and general reportings about your contact pool.
- **Mailings**Manage and control your mailings.
- **Transactions**Manage transaction endpoints (events) or send new transactions to trigger sendouts or Marketing Automation programs.
- **Marketing Automations**Start your predefined Marketing Automation programs.
- **Accounts**Configure specific account features.
- **Medias**Manage mailing templates.
- **Webhooks**Manage automatic data distributions to notify external systems of specific events.
- **Data Extensions**Create, update, and delete data extensions (custom tables). Import, query, and bulk-delete records using all five import modes: INSERT, UPDATE, UPSERT, INSERT\_IGNORE\_DUPLICATES, DELETE.
- **Mailing Blacklists**Create and manage named blacklists that suppress specific addresses from mailings. Add or retrieve blacklist expressions (patterns) per list.
- **Ping**Verify connectivity and API key validity by sending test GET, PUT, POST, or DELETE requests to the API.

Response handling
-----------------

[](#response-handling)

Every service method returns a `MaileonAPIResult` object. Use the following methods to inspect it:

MethodReturn typeDescription`isSuccess()``bool``true` if the HTTP status code is 2xx`isClientError()``bool``true` if the HTTP status code is 4xx`getStatusCode()``int`The raw HTTP status code`getResult()``mixed`The deserialized response payload (typed object, array, or raw string depending on endpoint)`getResultXML()``SimpleXMLElement|null`The response body parsed as XML, or `null` if the response was not XML`getBodyData()``string|null`The raw response body string`getResponseHeader(string $header)``string|null`A single response header value by name (case-insensitive)`getResponseHeaders()``array`All response headers as an associative arrayThe `x-pages` response header is used by paginated endpoints to indicate the total number of available pages.

When `THROW_EXCEPTION` is `true` (default), connection errors and 5xx responses throw a `MaileonAPIException`. When it is `false`, those calls return `null` — check for `null` before calling any method on the result.

```
$response = $service->someMethod();

if ($response === null || !$response->isSuccess()) {
    // handle error — getResultXML()->message often contains the API error description
    $message = $response?->getResultXML()?->message ?? 'Unknown error';
    throw new RuntimeException((string) $message);
}

$data = $response->getResult();
```

Examples
--------

[](#examples)

### Contact examples

[](#contact-examples)

- Request basic **contact data** identified by their email address:

```