BulkEmailSetup API

Getting Started

This is the documentation for the BulkEmailSetup PHP SDK.
In order to integrate BulkEmailSetup Email Sending Application with 3rd-party apps or any custom apps, you can use its 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.
This PHP SDK you will get with your application after the server setup.

HTTP Methods

We follow the REST standards for BulkEmailSetup’s API interaction, which means that we use the 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 its configuration to allow these methods.

Setup

Require the autoloader class if you haven’t used the Composer to install the package.

require_once dirname(__FILE__) . '/../BulkEmailSetupApi/Autoloader.php';

BulkEmailSetupApi_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('BulkEmailSetupApi_Autoloader', 'autoloader'), true);

Configuration object (Get your API info from your application API section).

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

Now inject the configuration and we are ready to make API calls.

BulkEmailSetupApi_Base::setConfig($config);

Start UTC

date_default_timezone_set('UTC');

Note:

Configuration components: The API for the BulkMailSetup 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 BulkEmailSetupApi/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 BulkEmailSetupApi_Endpoint_Lists();

1. Create a list

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

$response = $endpoint->create(array(
 // required fields
 '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 fields
 'defaults' => array(
 'from_name' => 'John Doe', // required
 'from_email'=> '[email protected]', // required
 'reply_to' => '[email protected]', // required
 'subject' => 'Hello!',
 ),
 // optional fields
 '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' => '[email protected]',
 'unsubscribe_to' => '[email protected]',
 ),
 // optional fields, if not set customer company data will be used
 'company' => array(
 'name' => 'Demo INC', // required
 'country' => 'United States', // required
 'zone' => 'New York', // required
 'address_1' => 'Street address', // required
 'address_2' => '',
 'zone_name' => '', // when country doesn't have required zone.
 'city' => 'New York City',
 'zip_code' => '30014',
 ),
));
// and get the response
print_r($response->body);

2. Update a list

$response = $endpoint->update('LIST-UNIQUE-ID', array(
 // required fields
 '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 fields
 'defaults' => array(
 'from_name' => 'John Doe', // required
 'from_email'=> '[email protected]', // required
 'reply_to' => '[email protected]', // required
 'subject' => 'Hello!',
 ),
 // optional fields
 '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' => '[email protected]',
 'unsubscribe_to' => '[email protected]',
 ),
 // optional, if not set customer company data will be used
 'company' => array(
 'name' => 'Demo INC', // required
 'country' => 'United States', // required
 'zone' => 'New York', // required
 'address_1' => 'Street address', // required
 'address_2' => '',
 'zone_name' => '',
 'city' => 'New York City',
 'zip_code' => '30014',
 ),
));
// and get the response
print_r($response->body);
 Delete a list

3. Delete a list

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

4. Copy a list

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

5. Get a list

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

6. 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 BulkEmailSetupApi_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 BulkEmailSetupApi_Endpoint_ListSegments();

Get all segments

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

Subscribers

Create the endpoint.

$endpoint = new BulkEmailSetupApi_Endpoint_ListSubscribers();

1. Create a subscriber

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

2. Update a subscriber

$response = $endpoint->update('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', array(
 'EMAIL' => '[email protected]',
 'FNAME' => 'John',
 'LNAME' => 'Doe Updated'
 ));
 // DISPLAY RESPONSE
 print_r($response->body);
 /*===================================================================================*/
 // CREATE / UPDATE EXISTING SUBSCRIBER
 $response = $endpoint->createUpdate('LIST-UNIQUE-ID', array(
 'EMAIL' => '[email protected]',
 'FNAME' => 'John',
 'LNAME' => 'Doe Updated Second time'
 ));
 // DISPLAY RESPONSE
 print_r($response->body);

3. 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', '[email protected]');
 // DISPLAY RESPONSE
 print_r($response->body);

4. 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', '[email protected]');
 // DISPLAY RESPONSE
 print_r($response->body);
 /*===================================================================================*/
 // SEARCH BY EMAIL IN ALL LISTS
 $response = $endpoint->emailSearchAllLists('[email protected]');
 // DISPLAY RESPONSE
 print_r($response->body);

5. 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', '[email protected]');
 // DISPLAY RESPONSE
 print_r($response->body);

6. Get one subscriber

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

7. 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 BulkEmailSetupApi_Endpoint_Campaigns();

1. 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' => '[email protected]', // required
 'subject' => 'Hey, i am testing the campaigns via API', // required
 'reply_to' => '[email protected]', // 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);

2. 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' => '[email protected]', // optional at update
 'subject' => 'Hey, i am testing the campaigns via API', // optional at update
 'reply_to' => '[email protected]', // 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);

3. Delete a campaign

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

4. Copy a campaign

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

5.Pause / Unpause a campaign

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

6. Mark a campaign as sent

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

7. Get a campaign

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

8. Get all campaigns

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

Campaigns tracking

Create the endpoint

$endpoint = new BulkEmailSetupApi_Endpoint_CampaignsTracking();

1. Track subscriber click for campaign

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

2. Track subscriber open for campaign

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

3. 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 BulkEmailSetupApi_Endpoint_CampaignBounces();

1. 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);

2. 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 BulkEmailSetupApi_Endpoint_Countries();

1. Get all countries

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

2. Get zones

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

Customers

Create the endpoint

$endpoint = new BulkEmailSetupApi_Endpoint_Customers();

1. Create customer

$response = $endpoint->create(array(
    'customer' => array(
        'first_name' => 'John',
        'last_name'  => 'Doe',
        'email'      => '[email protected]',
        'password'   => 'Password',
        'timezone'   => 'UTC',
    ),
    // company is optional, unless required from app settings
    'company'  => array(
        'name'     => 'Demo 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' => 33222,
        'address_1'=> 'Address',
        'address_2'=> 'Other Address',
    ),
));
// DISPLAY RESPONSE
print_r($response->body);

Templates

Create the endpoint

$endpoint = new BulkEmailSetupApi_Endpoint_Templates();

1. 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);

2. 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);

3. Delete template

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

4. Search template

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

5. Get one template

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

6. Get all templates

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

Transactional emails

Create the endpoint

$endpoint = new BulkEmailSetupApi_Endpoint_TransactionalEmails();

1. Create email

$response = $endpoint->create(array(
    'to_name'           => 'John Doe', // required
    'to_email'          => '[email protected]', // required
    'from_name'         => 'Jane Doe', // required
    'from_email'        => '[email protected]', // optional
    'reply_to_name'     => 'Jane Doe', // optional
    'reply_to_email'    => '[email protected]', // 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);

2. Delete email

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

3. Get one email

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

4. Get all emails

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

Let's Build this Thing Together!

1,632 Customers are already sending Millions of emails and generating tons of traffics for their business with BulkEmailSetup. Join The most empowered email sending provider.

Schedule a Call

BulkEmailSetup

Our aimed to offer a range of best-value products and services along with cutting-edge technology and dedicated round-the-clock customer support.



1st Floor, EFC Tech Center,
JKInfotech 2, Phase 1 Hinjewadi,
Rajiv Gandhi Infotech Park,
Pune, Maharashtra 411057, India



[email protected]
[email protected]

COMPANY

About Us
Contact Us
Blogpost

Email Sending Made Simple

BulkEmailSetup is fully
GDPR Compliant

RESOURCES

Demo Account
Pricing
Knowledge Base
Pre-Sales FAQs
Documentation
Video Tutorials
My Support Request

TERMS

This site is owned and operated by Goletro Technologies Private Limited

BulkEmailSetup API

Getting Started

HTTP Methods

Setup

Note:

Lists

1. Create a list

2. Update a list

3. Delete a list

4. Copy a list

5. Get a list

6. Get all lists

Fields

Get all fields

Segments

Get all segments

Subscribers

1. Create a subscriber

2. Update a subscriber

3. Delete a subscriber

4. Search subscribers

5. Unsubscribe subscribers

6. Get one subscriber

7. Get all subscribers

Campaigns

1. Create a campaign

2. Update a campaign

3. Delete a campaign

4. Copy a campaign

5.Pause / Unpause a campaign

6. Mark a campaign as sent

7. Get a campaign

8. Get all campaigns

Campaigns tracking

1. Track subscriber click for campaign

2. Track subscriber open for campaign

3. Track campaign unsubscribe

Campaigns bounces

1. Create a bounce

2. Get all bounces

Countries

1. Get all countries

2. Get zones

Customers

1. Create customer

Templates

1. Create template

2. Update template

3. Delete template

4. Search template

5. Get one template

6. Get all templates

Transactional emails

1. Create email

2. Delete email

3. Get one email

4. Get all emails

Let's Build this Thing Together!

Pin It on Pinterest