loading-img

Introduction

This is the documentation for the MailWizz PHP SDK.
In order to integrate MailWizz 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/mailwizz-python-sdk - The Python SDK.

https://github.com/twisted1919/mailwizz-ruby-sdk - The Ruby SDK.

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

https://www.npmjs.com/package/node-mailwizz - Node.js implementations

Getting started

Mailwizz PHP SDK

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

composer require twisted1919/mailwizz-php-sdk

HTTP Methods

We follow the REST standards for MailWizz'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__) . '/../MailWizzApi/Autoloader.php';
Register the autoloader if you haven't used composer to install the package
MailWizzApi_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('MailWizzApi_Autoloader', 'autoloader'), true);
Configuration object (Get your API info from: https://kb.mailwizz.com/articles/find-api-info/) :
$config = new MailWizzApi_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
MailWizzApi_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 MailWizz 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 MailWizz 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 MailWizzApi/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 MailWizzApi_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 MailWizzApi_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 MailWizzApi_Endpoint_ListSegments();
Get all segments
$response = $endpoint->getSegments('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);

Subscribers

Create the endpoint

$endpoint = new MailWizzApi_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);
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 MailWizzApi_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 MAILWIZZ >= 1.3.7.3
$endpoint = new MailWizzApi_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 MailWizzApi_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 MailWizzApi_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 MailWizzApi_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 MailWizzApi_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);
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 MailWizzApi_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);