Ai Email Solutions - API Documentation

Introduction

This is the documentation for the Ai Email Solutions PHP SDK.
In order to integrate Ai Email Solutions with 3rd-party apps or any custom apps, you can use it’s powerful API for which we also provide a PHP SDK for a quick PHP integration. The API is providing the basic operations needed for your implementation. This document will drive you through the PHP SDK .

Other implemetations:

https://github.com/twisted1919/Ai Email Solutions-python-sdk - The Python SDK.

https://github.com/twisted1919/Ai Email Solutions-ruby-sdk - The Ruby SDK.

https://github.com/thangtx/Ai Email Solutionsphpapi-wrap - A small rest app that acts as a proxy between mailwizz and any other software.

https://www.npmjs.com/package/node-Ai Email Solutions - Node.js implementations

Getting started

Ai Email Solutions PHP SDK

You can either download latest version of the code or you can install it via composer as follows:

composer require twisted1919/Ai Email Solutions-php-sdk

HTTP Methods

We follow the REST standards for Ai Email Solutions's API interaction, which means that we use following HTTP methods during communication:
1. POST - when items are created
2. GET - when items are listed
3. PUT - when items are updated
4. DELETE - when items are deleted
You will have to make sure your server supports all these methods.
If you are doing API calls and get HTTP Forbidden errors, when updating or deleting items, it means your server does not support PUT/DELETE and you must change it's configuration to allow these methods.

Setup

Require the autoloader class if you haven't used composer to install the package

require_once dirname(__FILE__) . '/../Ai Email SolutionsApi/Autoloader.php';

Ai Email SolutionsApi_Autoloader::register();

If using a framework that already uses an autoloading mechanism, like Yii for example, you can register the autoloader like:

Yii::registerAutoloader(array('Ai Email SolutionsApi_Autoloader', 'autoloader'), true);

Configuration object (Get your API info from: https://kb.Ai Email Solutions.com/articles/find-api-info/) :

$config = new aiemailsolutionsApi_Config(array(
    'apiUrl'        => 'http://www.mailwizz-powered-website.tld/api',
    'publicKey'     => 'PUBLIC-KEY',
    'privateKey'    => 'PRIVATE-KEY'
));

Now inject the configuration and we are ready to make api calls

aiemailsolutionsApi_Base::setConfig($config);

Start UTC

date_default_timezone_set('UTC');

Notes

If SSL present on the webhost, the api can be accessed via SSL as well (https://...). A self signed SSL certificate will work just fine.

If the Ai Email Solutions powered website doesn't use clean urls, make sure your apiUrl has the index.php part of url included, i.e: http://www.mailwizz-powered-website.tld/api/index.php

Configuration components: The api for the Ai Email Solutions EMA is designed to return proper etags when GET requests are made. We can use this to cache the request response in order to decrease loading time therefore improving performance. In this case, we will need to use a cache component that will store the responses and a file cache will do it just fine. Please see Ai Email SolutionsApi/Cache for a list of available cache components and their usage.

Lists

This API endpoint is allowing a user to create/update/delete/copy/retrieve lists and their related info.

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_Lists();

Create a list

Please see countries.php example file for a list of allowed countries/zones for list company

$response = $endpoint->create(array(
    // required
    'general' => array(
        'name'          => 'My list created from the API', // required
        'description'   => 'This is a test list, created from the API.', // required
        'opt_in'        => 'single' //optional
    ),
    // required
    'defaults' => array(
        'from_name' => 'John Doe', // required
        'from_email'=> 'johndoe@doe.com', // required
        'reply_to'  => 'johndoe@doe.com', // required
        'subject'   => 'Hello!',
    ),
    // optional
    'notifications' => array(
        // notification when new subscriber added
        'subscribe'         => 'yes', // yes|no
        // notification when subscriber unsubscribes
        'unsubscribe'       => 'yes', // yes|no
        // where to send the notifications.
        'subscribe_to'      => 'johndoe@doe.com',
        'unsubscribe_to'    => 'johndoe@doe.com',
    ),
    // optional, if not set customer company data will be used
    'company' => array(
        'name'      => 'John Doe INC', // required
        'country'   => 'United States', // required
        'zone'      => 'New York', // required
        'address_1' => 'Some street address', // required
        'address_2' => '',
        'zone_name' => '', // when country doesn't have required zone.
        'city'      => 'New York City',
        'zip_code'  => '10019',
    ),
));
// and get the response
print_r($response->body);

Update a list

$response = $endpoint->update('LIST-UNIQUE-ID', array(
    // required
    'general' => array(
        'name'          => 'My list created from the API - now updated!', // required
        'description'   => 'This is a test list, created from the API.', // required
        'opt_in'        => 'single' //optional
    ),
    // required
    'defaults' => array(
        'from_name' => 'John Doe', // required
        'from_email'=> 'johndoe@doe.com', // required
        'reply_to'  => 'johndoe@doe.com', // required
        'subject'   => 'Hello!',
    ),
    // optional
    'notifications' => array(
        // notification when new subscriber added
        'subscribe'         => 'yes', // yes|no
        // notification when subscriber unsubscribes
        'unsubscribe'       => 'yes', // yes|no
        // where to send the notifications.
        'subscribe_to'      => 'johndoe@doe.com',
        'unsubscribe_to'    => 'johndoe@doe.com',
    ),
    // optional, if not set customer company data will be used
    'company' => array(
        'name'      => 'John Doe INC', // required
        'country'   => 'United States', // required
        'zone'      => 'New York', // required
        'address_1' => 'Some street address', // required
        'address_2' => '',
        'zone_name' => '',
        'city'      => 'New York City',
        'zip_code'  => '10019',
    ),
));
// and get the response
print_r($response->body);

Delete a list

$response = $endpoint->delete('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Copy a list

$response = $endpoint->copy('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Get a list

$response = $endpoint->getList('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Get all lists

$response = $endpoint->getLists($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);

Fields

This API endpoint is allowing the user to get the available fields of a list

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_ListFields();

Get all fields

$response = $endpoint->getFields('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Segments

This API endpoint is allowing the users to retrieve the segments of a list

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_ListSegments();

Get all segments

$response = $endpoint->getSegments('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Subscribers

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_ListSubscribers();

Create a subscriber

$response = $endpoint->create('LIST-UNIQUE-ID', array(
    'EMAIL'    => 'john.doe@doe.com', // the confirmation email will be sent!!! Use valid email address
    'FNAME'    => 'John',
    'LNAME'    => 'Doe'
));
// DISPLAY RESPONSE
print_r($response->body);

Update a subscriber

$response = $endpoint->update('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', array(
    'EMAIL'    => 'john.doe@doe.com',
    'FNAME'    => 'John',
    'LNAME'    => 'Doe Updated'
));
// DISPLAY RESPONSE
print_r($response->body);
/*===================================================================================*/
// CREATE / UPDATE EXISTING SUBSCRIBER
$response = $endpoint->createUpdate('LIST-UNIQUE-ID', array(
    'EMAIL'    => 'john.doe@doe.com',
    'FNAME'    => 'John',
    'LNAME'    => 'Doe Updated Second time'
));
// DISPLAY RESPONSE
print_r($response->body);

Delete a subscriber

$response = $endpoint->delete('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
/*===================================================================================*/
// DELETE SUBSCRIBER by email address, no email is sent, delete is silent
$response = $endpoint->deleteByEmail('LIST-UNIQUE-ID', 'john@doe.com');
// DISPLAY RESPONSE
print_r($response->body);

Search subscribers

The search is done using the subscriber email. The search can be done on one list or on all the lists as in the below examples.

$response = $endpoint->emailSearch('LIST-UNIQUE-ID', 'john.doe@doe.com');
// DISPLAY RESPONSE
print_r($response->body);
/*===================================================================================*/
// SEARCH BY EMAIL IN ALL LISTS
$response = $endpoint->emailSearchAllLists('john.doe@doe.com');
// DISPLAY RESPONSE
print_r($response->body);

Unsubscribe subscribers

Unsubscribe existing subscriber by email address or its unique ID, no email is sent, unsubscribe is silent

$response = $endpoint->unsubscribe('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
/*===================================================================================*/
$response = $endpoint->unsubscribeByEmail('LIST-UNIQUE-ID', 'john@doe.com');
// DISPLAY RESPONSE
print_r($response->body);

Unsubscribe subscriber from all lists

Unsubscribe existing subscriber from all lists, no email is sent, unsubscribe is silent

$response = $endpoint->unsubscribeByEmailFromAllLists('john@doe.com');
// DISPLAY RESPONSE
print_r($response->body);

Get one subscriber

$response = $endpoint->getSubscriber('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Get all subscribers

$response = $endpoint->getSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);

Campaigns

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_Campaigns();

Create a campaign

$response = $endpoint->create(array(
    'name'          => 'My API Campaign', // required
    'type'          => 'regular', // optional: regular or autoresponder
    'from_name'     => 'John Doe', // required
    'from_email'    => 'john.doe@doe.com', // required
    'subject'       => 'Hey, i am testing the campaigns via API', // required
    'reply_to'      => 'john.doe@doe.com', // required
    'send_at'       => date('Y-m-d H:i:s', strtotime('+10 hours')), // required, this will use the timezone which customer selected
    'list_uid'      => 'LIST-UNIQUE-ID', // required
    'segment_uid'   => 'SEGMENT-UNIQUE-ID',// optional, only to narrow down

    // optional block, defaults are shown
    'options' => array(
        'url_tracking'      => 'no', // yes | no
        'json_feed'         => 'no', // yes | no
        'xml_feed'          => 'no', // yes | no
        'plain_text_email'  => 'yes',// yes | no
        'email_stats'       => null, // a valid email address where we should send the stats after campaign done

        // - if autoresponder uncomment bellow:
        //'autoresponder_event'            => 'AFTER-SUBSCRIBE', // AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
        //'autoresponder_time_unit'        => 'hour', // minute, hour, day, week, month, year
        //'autoresponder_time_value'       => 1, // 1 hour after event
        //'autoresponder_open_campaign_id' => 1, // INT id of campaign, only if event is AFTER-CAMPAIGN-OPEN,

        // - if this campaign is advanced recurring, you can set a cron job style frequency.
        // - please note that this applies only for regular campaigns.
        //'cronjob'         => '0 0 * * *', // once a day
        //'cronjob_enabled' => 1, // 1 or 0
    ),

    // required block, archive or template_uid or content => required.
    // the templates examples can be found here: Examples
    'template' => array(
        //'archive'         => file_get_contents(dirname(__FILE__) . '/template-example.zip'),
        //'template_uid'    => 'TEMPLATE-UNIQUE-ID',
        'content'           => file_get_contents(dirname(__FILE__) . '/template-example.html'),
        'inline_css'        => 'no', // yes | no
        'plain_text'        => null, // leave empty to auto generate
        'auto_plain_text'   => 'yes', // yes | no
    ),
));
// DISPLAY RESPONSE
print_r($response->body);

Update a campaign

$response = $endpoint->update('CAMPAIGN-UNIQUE-ID', array(
    'name'          => 'My API Campaign UPDATED', // optional at update
    'from_name'     => 'John Doe', // optional at update
    'from_email'    => 'john.doe@doe.com', // optional at update
    'subject'       => 'Hey, i am testing the campaigns via API', // optional at update
    'reply_to'      => 'john.doe@doe.com', // optional at update
    'send_at'       => date('Y-m-d H:i:s', strtotime('+1 hour')), //optional at update, this will use the timezone which customer selected
    'list_uid'      => 'LIST-UNIQUE-ID', // optional at update
    'segment_uid'   => 'SEGMENT-UNIQUE-ID',// optional, only to narrow down

    // optional block, defaults are shown
    'options' => array(
        'url_tracking'      => 'no', // yes | no
        'json_feed'         => 'no', // yes | no
        'xml_feed'          => 'no', // yes | no
        'plain_text_email'  => 'yes',// yes | no
        'email_stats'       => null, // a valid email address where we should send the stats after campaign done
    ),

    // optional block at update, archive or template_uid or content => required.
    // the templates examples can be found here: Examples
    'template' => array(
        //'archive'         => file_get_contents(dirname(__FILE__) . '/template-example.zip'),
        //'template_uid'    => 'TEMPLATE-UNIQUE-ID',
        'content'           => file_get_contents(dirname(__FILE__) . '/template-example.html'),
        'inline_css'        => 'no', // yes | no
        'plain_text'        => null, // leave empty to auto generate
        'auto_plain_text'   => 'yes', // yes | no
    ),
));
// DISPLAY RESPONSE
print_r($response->body);

Delete a campaign

$response = $endpoint->delete('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Copy a campaign

$response = $endpoint->copy('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Pause / Unpause a campaign

$response = $endpoint->pauseUnpause('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Mark a campaign as sent

$response = $endpoint->markSent('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Get a campaign

$response = $endpoint->getCampaign('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Get all campaigns

$response = $endpoint->getCampaigns($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);

Campaigns tracking

Create the endpoint

// PLEASE NOTE THAT THIS ENDPOINT ONLY WORKS WITH Ai Email Solutions >= 1.3.7.3
$endpoint = new aiemailsolutionsApi_Endpoint_CampaignsTracking();

Track subscriber click for campaign

$response = $endpoint->trackUrl('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', 'URL-HASH');
// DISPLAY RESPONSE
print_r($response->body);

Track subscriber open for campaign

$response = $endpoint->trackOpening('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Track campaign unsubscribe

$response = $endpoint->trackUnsubscribe('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', array(
    'ip_address' => '123.123.123.123',
    'user_agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36',
    'reason'     => 'Reason for unsubscribe!',
));
// DISPLAY RESPONSE
print_r($response->body);

Campaigns bounces

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_CampaignBounces();

Create a bounce

$response = $endpoint->create('CAMPAIGN-UNIQUE-ID', array(
    'message'        => 'The reason why this email bounced', // max 250 chars
    'bounce_type'    => 'hard', // hard, soft or internal
    'subscriber_uid' => 'SUBSCRIBER-UNIQUE-ID' // 13 chars unique subscriber identifier
));
// DISPLAY RESPONSE
print_r($response->body);

Get all bounces

$response = $endpoint->getBounces($campaignUid = 'CAMPAIGN-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);

Countries

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_Countries();

Get all countries

$response = $endpoint->getCountries($pageNumber = 23, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);

Get zones

$response = $endpoint->getZones(223, $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);

Customers

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_Customers();

Create customer

$response = $endpoint->create(array(
    'customer' => array(
        'first_name' => 'John',
        'last_name'  => 'Doe',
        'email'      => 'john.doe@doe.com',
        'password'   => 'superDuperPassword',
        'timezone'   => 'UTC',
    ),
    // company is optional, unless required from app settings
    'company'  => array(
        'name'     => 'John Doe LLC',
        'country'  => 'United States', // see the countries endpoint for available countries and their zones
        'zone'     => 'New York', // see the countries endpoint for available countries and their zones
        'city'     => 'Brooklyn',
        'zip_code' => 11222,
        'address_1'=> 'Some Address',
        'address_2'=> 'Some Other Address',
    ),
));
// DISPLAY RESPONSE
print_r($response->body);

Templates

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_Templates();

Create template

$rand = rand();
$response = $endpoint->create(array(
    'name'          => 'My API template ' . $rand,
    'content'       => file_get_contents(dirname(__FILE__) . '/template-example.html'),
    //'archive'     => file_get_contents(dirname(__FILE__) . '/template-example.zip'),
    'inline_css'    => 'no',// yes|no
));
// DISPLAY RESPONSE
print_r($response->body);

Update template

$response = $endpoint->update('TEMPLATE-UNIQUE-ID', array(
    'name'          => 'My API template - updated' . $rand,
    'content'       => file_get_contents(dirname(__FILE__) . '/template-example.html'),
    //'archive'     => file_get_contents(dirname(__FILE__) . '/template-example.zip'),
    'inline_css'    => 'no',// yes|no
));
// DISPLAY RESPONSE
print_r($response->body);

Delete template

$response = $endpoint->delete('TEMPLATE-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Search template

// Search ALL ITEMS (available from Ai Email Solutions 1.4.4)
$response = $endpoint->searchTemplates($pageNumber = 1, $perPage = 10, array(
    'name' => 'my template name'
));
// DISPLAY RESPONSE
print_r($response->body);

Get one template

$response = $endpoint->getTemplate('TEMPLATE-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Get all templates

$response = $endpoint->getTemplates($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);

Transactional emails

Create the endpoint

$endpoint = new aiemailsolutionsApi_Endpoint_TransactionalEmails();

Create email

$response = $endpoint->create(array(
    'to_name'           => 'John Doe', // required
    'to_email'          => 'john@doe.com', // required
    'from_name'         => 'Jane Doe', // required
    'from_email'        => 'jane@doe.com', // optional
    'reply_to_name'     => 'Jane Doe', // optional
    'reply_to_email'    => 'jane@doe.com', // optional
    'subject'           => 'This is the email subject', // required
    'body'              => 'Hello world!', // required
    'plain_text'        => 'Hello world!', // optional, will be autogenerated if missing
    'send_at'           => date('Y-m-d H:i:s'),  // required, UTC date time in same format!
));
// DISPLAY RESPONSE
print_r($response->body);

Delete email

$response = $endpoint->delete('EMAIL-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Get one email

$response = $endpoint->getEmail('EMAIL-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Get all emails

$response = $endpoint->getEmails($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);

Ai Email Solutions API PHP SDK documentation

Introduction

Getting started

Ai Email Solutions PHP SDK

HTTP Methods

Setup

Notes

Lists

Create a list

Update a list

Delete a list

Copy a list

Get a list

Get all lists

Fields

Get all fields

Segments

Get all segments

Subscribers

Create a subscriber

Update a subscriber

Delete a subscriber

Search subscribers

Unsubscribe subscribers

Unsubscribe subscriber from all lists

Get one subscriber

Get all subscribers

Campaigns

Create a campaign

Update a campaign

Delete a campaign

Copy a campaign

Pause / Unpause a campaign

Mark a campaign as sent

Get a campaign

Get all campaigns

Campaigns tracking

Track subscriber click for campaign

Track subscriber open for campaign

Track campaign unsubscribe

Campaigns bounces

Create a bounce

Get all bounces

Countries

Get all countries

Get zones

Customers

Create customer

Templates

Create template

Update template

Delete template

Search template

Get one template

Get all templates

Transactional emails

Create email

Delete email

Get one email

Get all emails