README

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.

Requirements
Installation
Usage
Examples

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

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

Download the official SSL cert bundle by CURL from https://curl.haxx.se/ca/cacert.pem
Save the bundle to a directory that can be accessed by your PHP installation
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

You can add this library to your project using Composer:

composer require xqueue/maileon-api-client

Usage

The API client divides the features of Maileon's REST API into specific consumable services. Each service provides all functions of it's 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.
Contactfilters Segmentate 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.

Examples

Contact examples

Request basic contact data identified by their email address:

<?php

  use de\xqueue\maileon\api\client\contacts\ContactsService;

  require __DIR__ . '/vendor/autoload.php';

  $contactsService = new ContactsService([
      'API_KEY' => 'Your API key',
  ]);

  $contact = $contactsService->getContactByEmail('foo@bar.com')->getResult();

  /**
  * The contact object stores all information you requested.
  * 
  * Identifiers (Maileon ID, Maileon external id and email address), marketing permission
  * level, creation date and last update date are always included if they are set in Maileon.
  * 
  * ID: $contact->id
  * Email: $contact->email
  * Permission: $contact->permission->getType()
  */

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

<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

require __DIR__ . '/vendor/autoload.php';

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$getContact = $contactsService->getContactByEmail(
    email:'foo@bar.com',
    standard_fields:[StandardContactField::$FIRSTNAME],
    custom_fields:['My custom field in Maileon']
);

if (!$getContact->isSuccess()) {
    die($getContact->getResultXML()->message);
}

$contact = $getContact->getResult();

/**
 * The contact object stores all information you requested.
 * 
 * Identifiers (Maileon ID, Maileon external id and email address), marketing permission
 * level, creation date and last update date are always included if they are set in Maileon.
 * 
 * ID: $contact->id
 * Email: $contact->email
 * Permission: $contact->permission->getType()
 * First name: $contact->standard_fields[StandardContactField::$FIRSTNAME];
 * Custom field: $contact->custom_fields['My custom field in Maileon'];
 */

Create a contact in Maileon

<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\Contact;
use de\xqueue\maileon\api\client\contacts\Permission;
use de\xqueue\maileon\api\client\contacts\StandardContactField;
use de\xqueue\maileon\api\client\contacts\SynchronizationMode;

require __DIR__ . '/vendor/autoload.php';

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
    'DEBUG'=> true // Remove on production config!
]);

// Create the contact object
$newContact = new Contact();
$newContact->email = "max.mustermann@xqueue.com";
$newContact->permission = Permission::$NONE; // The initial permission of the newly created contact. This ccan be converted to DOI after DOI process or can be set to something else, e.g. SOI, here already

// If required, fill custom fields
$newContact->standard_fields[StandardContactField::$FIRSTNAME] = "Max";
$newContact->standard_fields[StandardContactField::$LASTNAME] = "Mustermann";

// Also customfields are available
//$newContact->custom_fields["type"] = "b2c";

// And a list of contact preferences can also be added
//$newContact->preferences = array(
//    new Preference('EmailSegment1', null, 'Email', 'true'),
//    new Preference('EmailSegment2', null, 'Email', 'true')
//);

// Configuration of behavior or additional data
$src = ""; // a free to be chosen key for the source of the subscription
$subscriptionPage = ""; // a free to be chosen key to identify the subscription page
$doi = true; // true = a DOI mailing will be issued, this will cause an error, if no DOI mail is active in the newsletter account
$doiplus = true; // true = DOI + agreement for single user tracking is enabled, so clicks and opens are not anonymously logged
$doimailingkey = ""; // if several DOI mailings are enabled, this key decides which DOI to trigger

$response = $contactsService->createContact($newContact, SynchronizationMode::$UPDATE, $src, $subscriptionPage, $doi, $doiplus, $doimailingkey);

Synchronize a larger list of contacts with Maileon

<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\Contacts;
use de\xqueue\maileon\api\client\contacts\Contact;
use de\xqueue\maileon\api\client\contacts\Permission;
use de\xqueue\maileon\api\client\contacts\SynchronizationMode;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

require __DIR__ . '/vendor/autoload.php';

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
    'DEBUG'=> true // Remove on production config!
]);

// Some setup variables, see https://maileon.com/support/synchronize-contacts/
$useExternalId = false;
$ignoreInvalidContacts = true;
$reimportUnsubscribedContacts = true;
$overridePermission = false;
$updateOnly = false;

// Creating 10.000 dummy contacts
$contactsToSyncTmp = new Contacts();
for ($i=0; $i<10000; $i++) {
    $contactsToSyncTmp->addContact(
        new Contact(
            null,
            'max_'.$i.'.mustermann@baunzt.de',
            null,
            'external-id-'.$i,
            $anonymous = null,
            array(
                StandardContactField::$LASTNAME => 'Mustermann',
                StandardContactField::$FIRSTNAME => 'Max_'.$i
            ),array(
                'my_customfield_1' => 'value_'.$i,
                'my_customfield_2' => 'another_value_'.$i
            )
}

$response = $contactsService->synchronizeContacts(
    $contactsToSyncTmp,
    Permission::$NONE,
    SynchronizationMode::$UPDATE,
    $useExternalId,
    $ignoreInvalidContacts,
    $reimportUnsubscribedContacts,
    $overridePermission,
    $updateOnly);

// The response contains some statistics and, if ignore_invalid_contatcs is set to true, information about possibly failed contact creations, see https://maileon.com/support/synchronize-contacts/#articleTOC_3

Report example

Print all unsubscriptions:

<?php

use de\xqueue\maileon\api\client\reports\ReportsService;

require __DIR__ . '/vendor/autoload.php';

$reportsService = new ReportsService([
    'API_KEY' => 'Your API key',
]);

$index = 1;
do {
    $getUnsubscribers = $reportsService->getUnsubscribers(
        pageIndex:$index++,
        pageSize:1000
    );
    
    foreach ($getUnsubscribers->getResult() as $unsubscriber) {
        printf('%s unsusbcribed in mailing %u at %s'.PHP_EOL,
            $unsubscriber->contact->email,
            $unsubscriber->mailingId,
            $unsubscriber->timestamp
        );
    }
} while($getUnsubscribers->getResponseHeaders()['X-Pages'] >= $index);

Get KPI data for a specific mailing:

<?php

use de\xqueue\maileon\api\client\reports\ReportsService;

require __DIR__ . '/vendor/autoload.php';

$reportsService = new ReportsService([
    'API_KEY' => 'Your API key',
]);

$mailingId = 123;

$recipients = $reportsService->getRecipientsCount(mailingIds:[$mailingId])->getResult();
$opens = $reportsService->getOpensCount(mailingIds:[$mailingId])->getResult();
$clicks = $reportsService->getClicksCount(mailingIds:[$mailingId])->getResult();
$unsubscribers = $reportsService->getUnsubscribersCount(mailingIds:[$mailingId])->getResult();
$conversions = $reportsService->getConversionsCount(mailingIds:[$mailingId])->getResult();

Mailing example

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

<?php

use de\xqueue\maileon\api\client\mailings\MailingsService;

require __DIR__ . '/vendor/autoload.php';

$mailingsService = new MailingsService([
    'API_KEY' => 'Your API key',
]);

$mailingId = $mailingsService->createMailing(
    name:'My campaign name',
    subject:'Hi [CONTACT|FIRSTNAME]! We got some news for you!'
)->getResult();

$mailingsService->setSender($mailingId, 'foo@bar.com');
$mailingsService->setSenderAlias($mailingId, 'Maileon news team');
$mailingsService->setHTMLContent(
    mailingId:$mailingId,
    html:'<html>...</html>',
    doImageGrabbing:true,
    doLinkTracking:true
);
$mailingsService->setTargetGroupId($mailingId, 123);
$mailingsService->sendMailingNow($mailingId);

Transaction example

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

<?php

use de\xqueue\maileon\api\client\transactions\ContactReference;
use de\xqueue\maileon\api\client\transactions\Transaction;
use de\xqueue\maileon\api\client\transactions\TransactionsService;

require __DIR__ . '/vendor/autoload.php';

$transactionsService = new TransactionsService([
    'API_KEY' => 'Your API key',
]);

$transaction = new Transaction();
$transaction->typeName = 'My event to trigger';

$transaction->contact = new ContactReference([
    'email' => 'foo@bar.com'
]);

$transaction->content = [
    'foo' => 'bar',
    'items' => [
        [
            'name' => 'foo',
            'quantity' => 2,
            'price' => 27.99
        ],
        [
            'name' => 'bar',
            'quantity' => 1,
            'price' => 16.49
        ],
    ],
];

$transactionsService->createTransactions([$transaction]);

xqueue / maileon-api-client

Maintainers

Details

Add Maintainer

Remove Maintainer