en - API documentation

INTRODUCTION


This is the documentation for the mailflatrate API.
In order to integrate mailfatrate 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.

>> Download PHP SDK here <<



Contents

 
  • Setup
     
  • Lists
     
  • Campaigns tracking
     
  • Campaigns bounces
     
  • Countries
     
  • Customers
     
  • Templates
     
  • Transactional emails
 


Setup


1. Require the autoloader class
require_once dirname(__FILE__) . '/../MailflatrateApi/Autoloader.php';
2. Register the autoloader if you haven't used composer to install the package
 
MailflatrateApi_Autoloader::register();
 
$config = new MailflatrateApi_Config(array(
    'apiUrl'        => 'https://app.mailflatrate.com/api',
    'publicKey'     => 'PUBLIC-KEY',
    'privateKey'    => 'PRIVATE-KEY'
));
MailflatrateApi_Base::setConfig($config);
 
 Lists
$mfr_api = new MailflatrateApi_Endpoint_Lists();
 
 Create a list
$response = $mfr_api->create(array(
    // required
    'general' => array(
        'name'          => 'My new list.', // required
        'description'   => 'This list is created via API', // required
    ),
    // required
    'defaults' => array(
        'from_name' => 'John Doe', // required
        'from_email'=> 'johndoe@email.com', // required
        'reply_to'  => 'johndoe@email.com', // required
        'subject'   => 'Hello World!',
    ),
    // 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@email.com',
        'unsubscribe_to'    => 'johndoe@email.com',
    ),
    // optional, if not set customer company data will be used
    'company' => array(
        'name'      => 'John Doe Ltd.', // required
        'country'   => 'United States', // required
        'zone'      => 'Los Angeles', // required
        'address_1' => 'Fake street 123', // required
        'address_2' => '',
        'zone_name' => '', // when country doesn't have required zone.
        'city'      => 'Los Angeles',
        'zip_code'  => '90001',
    ),
));
// and get the response
print_r($response->body);
 
 
 Update a list
$response = $mfr_api->update('LIST-UNIQUE-ID', array(
    // required
    'general' => array(
        'name'          => 'My new List- but updated!', // required
        'description'   => 'This list is created via API.', // required
    ),
    // required
    'defaults' => array(
        'from_name' => 'John Doe', // required
        'from_email'=> 'johndoe@email.com', // required
        'reply_to'  => 'johndoe@email.com', // required
        'subject'   => 'Hello World!',
    ),
    // 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@email.com',
        'unsubscribe_to'    => 'johndoe@email.com',
    ),
    // optional, if not set customer company data will be used
    'company' => array(
        'name'      => 'John Doe Ltd.', // required
        'country'   => 'United States', // required
        'zone'      => 'Los Angeles', // required
        'address_1' => 'Fake street 123, // required
        'address_2' => '',
        'zone_name' => '',
        'city'      => 'Los Angeles',
        'zip_code'  => '90001',
    ),
));
// and get the response
print_r($response->body);
 
 
 Delete a list
$response = $mfr_api->delete('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 
 Copy a list
$response = $mfr_api->copy('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 
 Get a list
$response = $mfr_api->getList('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 

 Get all lists
$response = $mfr_api->getLists($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);
 




 Fields
 

 Create the endpoint
$mfr_api= new MailflatrateApi_Endpoint_ListFields();

 Get all fields
$response = $mfr_api->getFields('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 




 Segments

 
 Create the endpoint
$mfr_api= new MailflatrateApi_Endpoint_ListSegments();

 Get all segments
$response = $mfr_api->getSegments('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 

Subscribers
 

 Create the endpoint
$mfr_api= new MailflatrateApi_Endpoint_ListSubscribers();
 
 Create a subscriber
$response = $afr-api->create('LIST-UNIQUE-ID', array(
    'EMAIL'    => 'johndoe@email.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 = $mfr_api->update('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', array(
    'EMAIL'    => 'johndoe@email.com',
    'FNAME'    => 'John',
    'LNAME'    => 'Doe Updated'
));
// DISPLAY RESPONSE
print_r($response->body);
/*===================================================================================*/
// CREATE / UPDATE EXISTING SUBSCRIBER
$response = $mfr_api->createUpdate('LIST-UNIQUE-ID', array(
    'EMAIL'    => 'johndoe@email.com',
    'FNAME'    => 'John',
    'LNAME'    => 'Doe Updated Second time'
));
// DISPLAY RESPONSE
print_r($response->body);
 
 
 Delete a subscriber
$response = $mfr_api->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 = $mfr_api->deleteByEmail('LIST-UNIQUE-ID', 'john@doe.com');
// DISPLAY RESPONSE
print_r($response->body);
 
 Search subscribers
$response = $mfr_api->emailSearch('LIST-UNIQUE-ID', 'johndoe@email.com');
// DISPLAY RESPONSE
print_r($response->body);
/*===================================================================================*/
// SEARCH BY EMAIL IN ALL LISTS
$response = $mfr_api->emailSearchAllLists('johndoe@email.com');
// DISPLAY RESPONSE
print_r($response->body);
 
 Unsubscribe subscribers
$response = $mfr_api->unsubscribe('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
/*===================================================================================*/
$response = $mfr_api->unsubscribeByEmail('LIST-UNIQUE-ID', 'johndoe@email.com');
// DISPLAY RESPONSE
print_r($response->body);
 
 
 Get one subscriber
$response = $mfr_api->getSubscriber('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Get all subscribers
$response = $mfr_api->getSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);




 Campaigns

 
 Create the endpoint
$mfr_api= new MailflatrateApi_Endpoint_Campaigns();
 
 Create a campaign
$response = $mfr_api->create(array(
    'name'          => 'My new campaign', // required
    'type'          => 'regular', // optional: regular or autoresponder
    'from_name'     => 'John Doe', // required
    'from_email'    => 'johndoe@email.com', // required
    'subject'       => 'Hey, i am testing the campaigns via API', // required
    'reply_to'      => 'johndoe@email.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 = $mfr_api->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 = $mfr_api->delete('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Copy a campaign
$response = $mfr_api->copy('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Pause / Unpause a campaign
$response = $mfr_api->pauseUnpause('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Mark a campaign as sent
$response = $mfr_api->markSent('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Get a campaign
$response = $mfr_api->getCampaign('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Get all campaigns
$response = $mfr_api->getCampaigns($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);
 

 

Campaigns tracking
 

 Create the endpoint
$mfr_api= new MailflatrateApi_Endpoint_CampaignsTracking();
 
 Track subscriber click for campaign
$response = $mfr_api->trackUrl('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', 'URL-HASH');
// DISPLAY RESPONSE
print_r($response->body);
 
 Track subscriber open for campaign
$response = $mfr_api->trackOpening('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Track campaign unsubscribe
$response = $mfr_api->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
$mfr_api= new MailflatrateApi_Endpoint_CampaignBounces();
 
 Create a bounce
$response = $mfr_api->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 = $mfr_api->getBounces($campaignUid = 'CAMPAIGN-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);
 

Countries

 
 Create the endpoint
$mfr_api= new MailflatrateApi_Endpoint_Countries();
 
 Get all countries
$response = $mfr_api->getCountries($pageNumber = 23, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);
 
 Get zones
$response = $mfr_api->getZones(223, $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);
 

Customers

 
 Create the endpoint
$mfr_api= new MailflatrateApi_Endpoint_Customers();
 
 Create customer
$response = $mfr_api->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
$mfr_api= new MailflatrateApi_Endpoint_Templates();
 
 Create template
$rand = rand();
$response = $mfr_api->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 = $mfr_api->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 = $mfr_api->delete('TEMPLATE-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Search template
$response = $mfr_api->searchTemplates($pageNumber = 1, $perPage = 10, array(
    'name' => 'my template name'
));
// DISPLAY RESPONSE
print_r($response->body);
 
 Get one template
$response = $mfr_api->getTemplate('TEMPLATE-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Get all templates
$response = $mfr_api->getTemplates($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);
 

Transactional emails

 
 Create the endpoint
$mfr_api= new MailflatrateApi_Endpoint_TransactionalEmails();
 
 Create email
$response = $mfr_api->create(array(
    'to_name'           => 'John Doe', // required
    'to_email'          => 'johndoe@email.com', // required
    'from_name'         => 'Jane Doe', // required
    'from_email'        => 'janedoe@email.com', // optional
    'reply_to_name'     => 'Jane Doe', // optional
    'reply_to_email'    => 'janedoe@email.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 = $mfr_api->delete('EMAIL-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Get one email
$response = $mfr_api->getEmail('EMAIL-UNIQUE-ID');
// DISPLAY RESPONSE
print_r($response->body);
 
 Get all emails
$response = $mfr_api->getEmails($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
print_r($response->body);


 
Kategorien: Informations

Ähnliche Artikel

en - CAN-SPAM Act: A Complianc...
Do you use email in your business? The CAN-SPAM Act, a law that sets the rules for commercial email,...
en - Campaign tags and filters
When sending a campaign, you are able to use a number of custom tags and filters. Most common tags a...
en - How to add SPF and DKIM i...
One of the most important things to reach the best results is, to send your campaigns with valid and...