BulkMail will be closed from 21 December to the 8th Jan 2019 for the festive season.
If you are an active client you can still send newsletters. Purchasing credits will resume again from 8th Jan 2019.

Resource Center

Browse the topics below to find out more

API Documentation

Introduction

The platform’s JSON API is a remotely accessible service API which has been developed to allow users to run many functions using JSON requests.

The API makes it possible to programmatically update and use your account without the need to physically log into the platform itself. The API functionality allows you to create contacts, get a specific contact's information, create new mailing lists, update a contact’s subscriptions and more!

Getting your API information

Before you can access any of the platform’s API functions you will first need to get the information needed to connect to our API.

The first things you will need is the API details, these can are within the user’s account and can be found by clicking the blue button on the top right corner of the account and then selecting the API option. On the API page, you will see 4 input fields with the Shard ID, Client ID, and Requests URL already provided. You will need to click “Request new API key” to create your authentication key.

Your page should now have something similar to the following bits of information:

Shard ID: 030
Client ID: 1
Requests URL: https://youraccount.bulkmailapp.co.za/api.php
Authentication Key: 901e40752d921ebfc472d915c4e0e1804efb8695

(Please save your account information as you will need this later on)

Next, you will need to either create a means of connecting your website to our API or you can freely use our PHP wrapper class that has been created for ease of use. If you would like to make use of this PHP wrapper class then please request it.

Once you’ve set up all of the above you are then ready to start coding your API requests, so let’s take a look at the available requests.

Sending a request

All requests will be sent to the Requests URL as POST requests over the HTTP protocol using JSON encoded data. Each request is a JSON encoded object with 3 properties:

Property Elements Description auth shard, client, Token Authentication parameters request section, command, arguments Arguments used to select the correct request params parameters Parameters used to process the request

The request arguments will always include the section and the command and optional extra arguments depending on which type of request is needed.The params are optional and different for each request.

Examples:

{"auth":{"shard":"013","client":1,"token":"416df33fb4b3b7c390ad771f67c486dc f3011feb"},"request":{"section":"api","command":"test"},"params":[]}
{"auth":{"shard":"013","client":1,"token":"5bfdd77872f0991d5934c0f59d7a4b8c a92c6c91"},"request":{"section":"contacts","command":"read","id":"1"},"para ms":[]}
{"auth":{"shard":"013","client":1,"token":"dd9313990ed9e53af2caeeee6ca88f9a 7cc63335"},"request":{"section":"contacts","command":"create"},"params":{"c _email":"This email address is being protected from spambots. You need JavaScript enabled to view it."}}

The server will respond with a HTTP status code 200 when the API request was processed successfully and will return a HTTP status code 40X if there are any errors. When a request is processed with errors the body of the response will include an array of all the returned errors which includes multiple errors organized by fields. This is useful when an update or create command is used in order to indicate which field was invalid.

Example:

{"email":["Email cannot be empty"],"domain":["Domain name is invalid"]}

Each request must present a token that is required to authenticate the request. The token is a hash encoded using SHA-1 algorithm of a string that concatenates the api key, the client id, the arguments and the parameters becoming in this way unique per request. The api key, arguments and parameters are also converted into a hash using MD5 algorithm before they are concatenated together. The following code snippet will serve as an example of how the token is generated.

$token = sha1(
md5($apiKey) . $clientId . md5(json_encode($arguments)) . md5(json_encode($params)) );

A wrapper class is available for PHP and can be used out of the box to interact with the API. The class can also serve as an example of how a wrapper can be implemented and also provide more information about how the internals of the API work.

There is an API command available which can be used to test the implementations of a wrapper or the authentication over API. The command can be requested using the section API and command test and will return an array with the value true for key ‘ok’ and a ‘params’ array which includes all the parameters passed to the request. If the request includes the argument ‘error’ with the value true, the test command will return a sample error.

Available requests

In this section below, we shall go through the requests that you’re currently able to do using the API. Further down this document, we will go through some example code to show you how it should look to perform a specific action.

Before we can start showing you the examples we need to go through the different sections that you can currently connect to via the API and the current commands you’re allowed to take per section. The list below will show you the Sections followed by the commands available for that section.

Section Command What it does API test Test to make sure the API is working contacts_api read Search for a contact by an email address contacts_api active Mark a contact as active contacts_api deactivate Mark a contact as inactive contacts read Get one contact by ID contacts create Create a new contact contacts update Update a contact contacts delete Delete a contact from the account fields read Get a list of all custom fields within the account fields read Get a custom fields by ID fields create Create a new custom fields fields delete Delete a custom field lists read Get a list of all the mailing list the account has lists read Get one mailing list by ID lists create Create a new mailing list lists delete Delete a mailing list subscriptions subscribe Subscribe a contact(s) to a list(s) subscriptions Unsubscribe Unsubscribe a contact(s) from a list(s) suppressions read Get a list of all the suppressions in the account suppressions read Get one suppression by ID suppressions add Add a new suppression suppressions delete Delete a suppression

Right, now we’ve got the current sections and their commands out of the way, we can now move on to some examples on how to code these requests.

Searching for a contact

You can easily send a request to the API to find out what information you currently store for that email address. When you search for an email address and a contact is found then you will get a result which contains the contacts field data that are stored against that email address, you will also get their current subscriptions and the contacts engagement rate (Opens, clicks etc..).

Below is an example on how to search for a contact via their email address:

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘contacts_api’, ‘command’ => ‘search’, ‘email’ => ‘This email address is being protected from spambots. You need JavaScript enabled to view it.’));
?>

You can also grab a contact by their ID within the platform which will bring back the same information as searching for their email address. For this you will need to know the individual contact’s ID number. An example of how to request this is below

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘contacts’, ‘command’ => ‘read’, ‘id’ => ‘20’));
?>

Adding a contact to your account with custom data

The following example code will create a new contact with some custom data, into your account but won’t add them to a subscription. This will just plainly add them into the overall database. You will need to connect to your account via the API first (as seen on the previous page) and then you will need to tell the API what request you’re trying to make.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘contacts’, ‘command’ => ‘create’)) ->setParams(array(
‘c_email’ => ‘This email address is being protected from spambots. You need JavaScript enabled to view it.’, ‘d_first_name’ => ‘John’, ‘d_last_name’ => ‘Doe’, ‘d_phone’ => ‘01200625302’ ‘f_1’ = > ‘England’ )); ?>

** f_1 is the field ID, you will need to know the fields ID in order to add more fields

Adding a contact to your account but subscribing to a list/lists

This has a very similar coding structure to when you’re just adding a contact to the main account. This time round we’re going to be adding them to your mailing account and subscribe them to a list. As you can see from the example below, you first connect to your account via the API, you then tell the API what request you’re trying to make. The parameters this time will be the same as above but with the added parameter for the lists.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘contacts’, ‘command’ => ‘create’)) ->setParams(array(
‘c_email’ => ‘This email address is being protected from spambots. You need JavaScript enabled to view it.’, ‘d_first_name’ => ‘John’, ‘d_last_name’ => ‘Doe’, ‘d_phone’ => ‘01200625302’ ‘f_1’ = > ‘England’ ‘actions’ => array(
array(‘action’ => ‘subscribe’, ‘lists’ => array(1)) ) )); ?>

As you can see we’ve added a new parameter called “actions” this is to tell the API what we want to happen with the contact you’re trying to add. The “lists” part is telling the platform which list you would like them to go in too. You will need to know the ID of the individual list you’re trying to add (if you get stuck on this then please contact our support team). You can add multiple list ID’s within the array by separating them via a comma.

Setting a contact as active/inactive

Marking a contact as inactive will mean they no longer receive any emails sent to them regardless of what list they are in. You can also mark them as active again if they’ve been made inactive in the past. The code below will show you an example of how to do this using the API.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘contacts_api’, ‘command’ => ‘deactivate’)) ->setParams(array(
‘contacts’ => array(1, 2, 4) )); ?>

As you can see there is only one parameter we need to add this time as we’re only editing the contacts activity status and not anything else. The example shows you how to make a contact as inactive, just change the command to ‘activate’ and this will turn a contact to active providing they are set to inactive in the account.

Updating a contact's details

As soon as a contact is in your account it is always good to keep their details up to date. As well as manually logging in and changing the contact details in the account you can also send a request to the platform to handle the changes for you. You will also be able to update the email address if needed as you will be updating the contact via their ID.

Below is an example of how to send a change request to the API

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘contacts’, ‘command’ => ‘update’, ‘id’ => 1)) ->setParams(array(
‘c_email’ => ‘This email address is being protected from spambots. You need JavaScript enabled to view it.’, ‘d_first_name’ => ‘Summer’, ‘d_last_name’ => ‘Update’, ‘d_phone’ => ‘01234567890’, ‘f_1’ => ‘England’, )); ?>

As you can see from the example above, the code is laid out in the same way as adding a new contact but this time the command is ‘update’ and you’re selecting which contact to edit by inputting the contact’s ID.

Deleting a contact

As well as creating new contacts and updating those contacts, you can also delete them. You will need to know the contacts ID which you can get automatically by searching for the contact information. There isn’t that much code needed to delete the contact as you will see in the example below.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘contacts’, ‘command’ => ‘delete’, ‘id’ => 1));
?>

Creating a custom field

Before adding any of your own custom data for each contact, like their address or country, you will first need to create a new field for this data to be imported into. Like many of the actions that can be undertaken in the API, you can also create a new custom field. The main parts that are required are the field name and the field type. There are only 3 types of fields you can choose from, these are text fields, date fields and a choices fields.

The parameters that can be used for this request depending on the type of field you would like to create.

If you would like to create a text field these are parameters you can use. The first 2 are required

  • name – The name of the field you would like to create (string)
  • type – This is the type of field you would like to create, either text/date/choices (string)
  • default_value – Set the default value for this field, it will be used if a contact has nothing set for this field (string)
  • rows_count – The number of rows you would like the field to contain, used in conjunction with forms (integer)
  • cols_count – The amount of columns you would like for the field, used in conjunction with forms (integer)
  • min_chars – The minimum amount of characters that are required, used in conjunction with forms (integer)
  • max_chars – Maximum amount characters that are allowed in this field, used in conjunction with forms (integer)

If you’re wanting to create a choice field then these are the parameters are required.

  • name – The name of the field you would like to create (string)
  • type – This is the type of field you would like to create, either text/date/choices (string)
  • format – The type of choice you would like to use, radio/dropdown/checkbox (string)
  • values – A list of options you would like included in the field (array)

Lastly, if you’re wanting to create a date field then the following parameters are required.

  • name – The name of the field you would like to create (string)
  • type – This is the type of field you would like to create, either text/date/choices (string)
  • min_year –The minimum date that the calendar will go back to (integer)
  • max_year – The maximum year the calendar will go up to too (integer)

Below is also a code example of how to implement this.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘fields’, ‘command’ => ‘create’)) ->setParams(array(
‘name’ => ‘address’, ‘type’ => ‘choices’, ‘format’ => ‘checkbox’, ‘values’ => array(choice 1, choice 2, choice 3) ));
?>

Viewing your custom fields

The API also returns all of the custom fields that are currently in the account. The following is an example on how to view this data

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘fields’, ‘command’ => ‘read’, ‘all’ => true)); ?>

You can also just bring back the information for one of the fields by adding the ID after the command.

The line of code should read similar to the below.

<?php
->setRequest(array(‘section’ => ‘fields’, ‘command => ‘read’, ‘id’ => 1)); ?>

Deleting a field

The same as contacts, the API also gives you the option to delete a custom field. The code needed for this is very similar to obtaining custom field via its ID, except this time the command is ‘delete’ rather than ‘read’

Example below

<?
php->setRequest(array(‘section’ => ‘fields’, ‘command’ => ‘delete’, ‘id’ => 1)); ?>

Creating a new list

Much like creating a new custom field and a new a contact, you can also create a list via the API. Before a contact can go into any list you will obviously need to create at least one list for the contact(s) to go into.

Below shows an example of how to create a list using the API

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘lists’, ‘command’ => ‘create’)) ->setParams(array(
‘name’ => ‘list 1’, ));
?>

You can also delete a list by changing the command to ‘delete’ instead of ‘create’. For deleting a list you don’t need any parameters.

Viewing all/one of the contact lists

As well as creating a new contact list you can also view all the contact lists you have in your account. An example of how to do this is below

<?php
->setRequest(array(‘section’ => ‘lists’, ‘command’ => ‘read’, ‘all’ => true)); ?>

To view one contact list on their own you would need to know the list ID and you’ll also need to make a slight change to the statement above by adding in the ID.

<?php
->setRequest(array(‘section’ => ‘lists’, ‘command’ => ‘read’, ‘id’ => 1)); ?>

Subscribing contacts to a list

You may feel that this has already been covered earlier on in the document however that only covered adding one contact to a list when you’re creating the contact from the beginning. This request allows you to modify the subscriptions for the contacts that are already in your account.

This request allows you to subscribe 1 or more contacts at a time and subscribe them to 1 or more lists in per request. An example of what is needed to perform this request is below.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘subscriptions’, ‘command’ => ‘subscribe’)) ->setParams(array(
‘contacts’ = > array(1,25,20,92), ‘lists’ => array(4,95,2), )); ?>

You can also use this request to bulk unsubscribe your contacts as well. You use the same parameters as subscribing a contact to a list but the command you use is different, you would replace ‘subscribe’ with ‘unsubscribe’, an example of this is below

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘subscriptions’, ‘command’ => ‘unsubscribe’)) ->setParams(array(
‘contacts’ = > array(1,25,20,92), ‘lists’ => array(4,95,2), ));
?>

Getting your current list of suppressed email addresses

As you may be aware the suppression list is a list of suppressed email address that has either unsubscribed from your emails or you’ve manually added them yourself, they are basically email address that you no longer want to email anymore.

Through the API you can get a list of all the suppressions in the account, the example below will show you how to do this.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘suppressions’, ‘command’ => ‘read’, ‘all’ => true)); ?>

You can also do a search for one contact if you know the ID, you can do this by adding the ID after the command like the example below.

<?php
->setRequest(array(‘section’ => ‘suppressions’, ‘command => ‘read’, ‘id’ => 25)); ?>

Adding/removing a contact from the suppression list

Adding to the API’s many functions you can also add a contact to the suppression list. You may want to do this based on a specific action that happens with your CRM or website, whatever the reason may be, the example below will show you how to utilise this function.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘suppressions’, ‘command’ => ‘add’)) ->setParams(array( ‘suppressions-list’ => ‘This email address is being protected from spambots. You need JavaScript enabled to view it.’, ‘bulk_notes’ => ‘Custom note for the suppressed email’, ‘list_id’ => false, ));
?>

You can also delete the contacts from the suppression list as well but you will need to know the ID of this email within the suppression list. An example of how to delete the email address is below.

<?php
require ‘MMAPI.php’; $shard_id = ‘030’; $client_id = ‘1’; $api_key = ‘0e7e3ki34163cf0620e9f5b73c12402f0df25ser’; $url = ‘https://youraccount.bulkmailapp.co.za/api.php’;
$api = new MMAPI(); $api->setup($shard_id, $client_id, $api_key, $url)
->setRequest(array(‘section’ => ‘suppressions’, ‘command’ => ‘add’, ‘id’ => 20)); ?>

 

{snippet back_overview} || API

Sign up for a free trial!

Want to try out BulkMail.
The Free Account gives you 100 FREE CREDITS to test drive the application
(Limited to 20 email addresses).

Signup Our signup process

Important: Read our Anti-Spam Policy to ensure that you are complying with our send policies, before you purchase credits.

About Us

It's never been easier to build your own newsletter or select and customise a free template with BulkMail email service.

Try out the best bulk email software today, create your email campaign and send bulk email.

Contact Us

Click here to send us a message.

Office hours: Mon-Thur 9h00 - 16h00 / Fri 9h00 - 13h00

Office: +27 (0)21 913 7872

Address:
21A Thor Circle
Thornton
Cape Town, 7460