xqueue/maileon-api-client

API-Client to XQ:Maileon

v1.9.5 2022-11-11 06:14 UTC

README

Latest Stable Version License PHP Version Require

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.

Table of contents

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:

  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):
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]);