Download the PHP package xqueue/maileon-api-client without Composer

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.

For runnable examples and integration tests see the maileon-php-api-client-examples repository.

Table of contents

• Requirements
• Installation
• Configuration
• Usage
• Response handling
• Examples
  • Contact examples
  • Report example
  • Mailing example
  • Data Extensions examples
  • Transaction example

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 https://curl.haxx.se/ca/cacert.pem
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):

Installation

You can add this library to your project using Composer:

Configuration

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

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 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

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

The 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.

Examples

Contact examples

• Request basic contact data identified by their email address:

• Request a contact identified by its email address including their first name and a predefined custom field and also check for a valid response:

• Create a contact in Maileon

• Synchronize a larger list of contacts in bulk

Report example

• Print all unsubscriptions:

• Get KPI data for a specific mailing:

Mailing example

• Create a new mailing, add custom HTML content, attach a target group and send it immediately:

Data Extensions examples

• Create a new data extension with two fields:

• Import records using UPSERT (insert new rows, update existing ones by unique key):

• Read all records page by page:

• Delete all records from a data extension:

Transaction example

• Send a new transaction including product information as an order confirmation: