beMail REST Api Documentation

General specifications

API call are REST based and input data is Json Encoded, a PHP sample to create a call is available at the end of this page. In order to simplify the caling process, the authentication process is based on a simple token and the HTTP method implemented are only 2: GET and POST.
The base url to call is https://rest.be-mail.it/
The token is sent to the server using the HTTP header X-bemail-auth

Data needed to generate the autentication Token

The token is generated with the following rule:

base_64({ API ID }_{ USER }_MD5([ PASSWORD ][ APIKEY ][YYYYMMDD]))


Variable Description
API ID Unique Console API ID assigned at startup
APIKEY a code assigned at API activation time
USER username used to log-in on beMail
PASSWORD password used to log-in on beMail
YYYYMMDD date of the request

Documentation and Explorer

The API have a documentation of each call that can be used to manage entities. The documentation is linked to a simple "API explorer" that permit you to call the API directly from the web.
Is also possible to use the entity Docs to get the documentation using the API itself.

In order to send a mailing from API ths list of calls needs to be executed:

Api Call
mailing/createMailing
mailing/linkHeader
mailing/linkFooter
mailing/pushDem
mailing/tackLinks (non mandatory)
mailing/linkTarget
mailing/sendTest
mailing/scheduleMailing

API Answer

The API answer of every call is a json encoded structure. It can contain an error or a return value.
The error structure will be:


{
	"error":
	{
		"message":[Error message],
		"type":[Error type],
		"code":[Error code]
	}
}
The success structure will be: 

{
	"code":200,
	"response":[response of each call]
}
Note.The answer of each call can be tested using the API explorer.


Example of use API in PHP


/*
 * Require BeMail Api Calss
 */
require_once 'bemail_api.php';

/*
 * Config Api Request
 */
$config = array('id'=>'ID',
                'key'=>'KEY',
                'username'=>'USERNAME',
                'password'=>'PASSWORD',
                'version'=>'v1'
                );
/*
 * Create Object Api BeMail
 */
$api = new bemail_api($config);

/*
 * Api request
 * 1° param => Request type (POST - GET)
 * 2° param => Request (Es° 'customer/getAll')
 * 3° param => Fields Post, "can be empty", (Es° array('key'=>'value')) 
 * 
 */
$json = $api->apiRequest('POST', 'mailing/sendTest', array('id_mailings'=>'123',
							   'email_list'=>array('email1@test.com',
									       'email2@bemail.it'
									       )
							   )
			 );

BeMail API Class in PHP


/*
  * BeMail Api
  * Version 1.0.0
  * 
  */
class bemail_api {
    
    private $id;
    private $api_key;
    private $user;
    private $password;
    private $token;
    private $version;
    private $request_url;
    private $url;
    
    function __construct($config)
    {
        $this->request_url = "https://rest.be-mail.it/";
        $this->id = $config['id'];
        $this->api_key = $config['key'];
        $this->user = $config['username'];
        $this->password = $config['password'];
        $this->version = $config['version'];
    }

    public function apiRequest($method = null, $request = null, $fields_post = null)
    {
        $this->generateHash();
        $this->generateRequestUrl($request);
        $method = strtoupper($method);
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->url);
        if(isset($method) && !empty($method) && $method = 'POST' && isset($fields_post) && is_array($fields_post))
        {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($fields_post));
        }
        curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-bemail-auth: '.$this->token));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $json = curl_exec($ch);
        
        curl_close($ch);
        
        return $json;
    }

    private function generateHash()
    {
        $hash = md5($this->password.$this->api_key.date('Ymd'));
        $this->token = base64_encode($this->id.'_'.$this->user.'_'.$hash);
    }

    private function generateRequestUrl($request)
    {
        $this->url = $this->request_url.'/'.$this->version.'/'.$request;
    }

}

beMail Api SDK

Type SDK Version Download
PHP 1.0.0 Download SDK