The unified blog for email marketing tips


Nov 142020

This post is intended to describe our 2 APIs that we have at this moment (14.11.2020), and could be updated as SMTPBOXES upgrades as well.
The first API that we are going to talk about is:

FRAPI (feedback response API).

This API serves as feedback to any web application you have by providing bounce statistics from the email letters sent via SMTPBOXES simple online platform (SOP) or your web application / SMTP Client.

With the help of the following figure, we will try to explain the entire email sending and bounce handling process. It really isn't that difficult that it seems.

Figure 1

 Let's go from the START of this scheme and follow the workflow.

STEP 1. No mater the method you choose (SMTP connection or our platform) the emails first get delivered to your SMTPBOX.

In rare situations your SMTPBOX could be offline or if your plan has expired, there would be immediate hard bounce to your SMTP Client.

If it is all okay with your SMTPBOX, your app will receive response that the email was successfully delivered. Well, this is true but only delivered to your SMTPBOX. There's a long way for your message to travel until it truly gets delivered to the recipient.

STEP 2. The mother server should now move your email by reaching the internet, then reach the server which sits behind the recipient and send the email. IF the email is delivered successfully there's no further action needed, because in the 1st step we already stated to your app a delivered response. But IF there's a bounce and you have set your FRAPI settings correct we go further to step 3.
Note: There's no need of FRAPI settings for our SOP, because it already works in conjunction with the Mother Server and displays a PIE graph. The FRAPI is mostly needed for a platform that you have.

STEP 3. Now as the FRAPI has received a hard or soft bounce from the recipient server, it will check your account and your email body for its requirements.
These requirements are: At least one action set correctly ( ie "Action on blocked email") and a div tag in your email body that looks like this -> <div style="display:none" id="smtpboxes_FRAPI_fr-1da3bdcc142de" name="my first frapi"></div> .

Take a look at the following figure as an example

Figure 2


 The FRAPI will send the request to your desired page (in this example frapi_reciever.php) and we move to step 4.


Step 4. This step is mainly for accepting the request from FRAPI and translating it to a way that your application can understand it and hopefully will mark the bounce in your campaign. This is vital step, as nothing from the FRAPI so far will make sense if it is not completed.
Keep in mind that you will probably need coding skills and the understanding on the API of your own application (MailWizz, Sendy, etc.).

Here's a PHP code example to obtain the main parameters from the bounce:
$bounced_email = urldecode($_POST['email']);
$bounced_time = urldecode($_POST['bouncetime']);
$bounced_type = urldecode($_POST['type']);
$subject = urldecode($_POST['emailsubject']);
$for_list= urldecode($_POST['forlist']);
/* Here we have coding with the API for your app in order to mark the email as bounced in your campaign */



Subscription API

For the sake of simplicity we will just place the available PHP code which has to do a POST request from your server to our page that accepts it. This is


$postData = array(
'0' => '',
'1' => 'John',
'2' => 'Travolta',
'GDPR_DATA' => '11/11/2020;23:59;New Jersey;moredata;moredata'
$postData = array('sub_info' => json_encode($postData));
$postCredentials = array('username_pass' => json_encode(array('username','YOUR-PASSWORD')));
$postList = array('sub_list' => 'all2.txt ');

$cURLConnection = curl_init('');
curl_setopt($cURLConnection, CURLOPT_POSTFIELDS, http_build_query(array($postData,$postCredentials,$postList)));
curl_setopt($cURLConnection, CURLOPT_RETURNTRANSFER, true);

$apiResponse = curl_exec($cURLConnection);
if($apiResponse=='Subscribed!'){/* Everything went well !*/} else{ /* Unable to subscribe */}

$postData is an array which can contain up to 15 elements ! All data provided will be stored to your list on successful request.
Keep in mind that you should put as little as information as possible, first because this is a main rule in GDPR and secondly the list should not exceed 2 megabytes when using the API. For reference 2 megabytes can hold up to 100 000 emails if used as in the example, and just 10 000 or even less if you put too much info.

For $postCredentials please replace "username" and "YOUR-PASSWORD" with your respected ones.
$postList is the list that the record would be stored. Keep in mind that it should already exist in "Manage Lists" section. To do that just upload .csv or .txt file to the system.

$cURLConnection is obvious one - the url to which you would do the post request.

$apiResponse has several important text responses that you can catch in case something goes wrong with the process.
In errors where you put wrong username/password or a list filename that does not exist on the smtpbox you would get "Bad Request" response.
Of course the most important thing is to put the valid email in the $postData array. If you don't, the response would be "No email found in your POST."
If your list grows over 2 megabytes the response would be "List too big (over 2MB).".
On successful subscription process the response would be "Subscribed!".


We hope the APIs are clear to understand and easy to use.
If you have any questions, you can always leave a comment here and we will try to help.


There are no published comments.

New comment