BulkEmailSetup API

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';

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

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.

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.

Bulk Email Setup Logo Small © bulkemailsetup.com

COMPANY
Visa, Mastercard, AMEX, Rupay, DIscover 2Checkout
Email Sending Made Simple
BulkEmailSetup - GDPR

BulkEmailSetup is fully
GDPR Compliant

Copyright © 2024 BulkEmailSetup.com

This site is owned and operated by Goletro Technologies Private Limited

Pin It on Pinterest