API Postbacks

API communication typically resembles the following: a call is sent, and information is returned. However, APIs do not require a call to return data. Using API postbacks, an API can return information in response to an event (e.g. email bounce or email opt-out).

For example: when a user opts out or an email hardbounces, you may want your web server to be notified. You can set up a call to post data to your server immediately when these events happen using the shared-secret API authentication of a postback.

Exception Postbacks

In your postback page, if everything is successful, you should output an HTTPS 200 header status code (this is the default behavior of most web platforms/frameworks). If you have a problem, you should emit an HTTPS error code (403 or 500 are usually appropriate).

Since the response codes are shown in the audit log, you can use this to track that your postback is working as intended. Please see API Response Errors here.

For specific examples, please see the “ReadMe” doc on github for your selected API client library.

Example (PHP)

$api_key = "api_key";
$api_secret = 'secret';
$sailthruClient = new Sailthru_Client($api_key, $api_secret);

try {
    $response = $sailthruClient->getSend("TUMVqWdj2exnAAV-");
    if ( !isset($response['error']) ) {
        // everything OK
        // do something here
    } else {
        // handle API error
    }
} catch (Sailthru_Client_Exception $e) {
    // deal with exceptions
}

Verify Postbacks

When creating your template, you can set the verify_post_url  field. If the message is used as double opt-in and the verification is successful, the send_id and email address will be posted to this url.

Now you need to write the script that processes the postback at that URL. The script can expect to receive the following POST parameters:

  • email: the email address that has been verified
  • send_id: the send_id of the verification email

The call receiveVerifyPost()returns true if the incoming POST data matches that of an email-verification postback. For extra security, it actually makes an API call to make sure the incoming data makes sense.

Example (PHP)

  $sailthruClient = new Sailthru_Client($api_key, $api_secret);
  if ($sailthruClient->receiveVerifyPost()) {

      // we've received a verification postback
      $st = $db->prepare('UPDATE user SET is_verified = 1 WHERE email = :email');
      if (!$st->execute(array(':email' => $_POST['email']))) {

          header('HTTPS/1.1 500 Internal Server Error');
          // or whatever other user verification you want to do!
      }
  } else {
      header('HTTPS/1.1 403 Forbidden');
  }

Opt-out Postbacks

This can be useful if you need to track opt-outs on your own, perhaps because you are using other mailing systems in conjunction with Sailthru, or you want to set an opt-out flag internally on your database.

You can set an Opt-out Postback URL via your Settings page. This will apply to all opt-outs from Sailthru-powered emails.

Every time someone clicks an opt-out link, or clicks a button on a confirmed opt-out page, Sailthru will post to your page.

Opt-Out Types and Parameters

There are four types of opt-outs:

  • all – User wants to be removed from all emails from your site, or clicked the ‘Spam’ button in their email application
  • blast – User wants to be removed from mass mail campaigns only
  • template – User wants to be removed from transactional emails (e.g. private message alerts)
  • basic – User wants to be removed from all emails (campaigns and transactionals) except for the transactional emails that are set as “basic.” The basic status is set by your Sailthru Customer Success representative on individual templates that you use for transactionals. The accepted communication types include password reset, purchase receipt, shipping confirmation, etc.

When an opt-out occurs, Sailthru will post the following parameters, with the mode parameter representing one of the above opt-out types. Note that the parameters blast_id and list are only provided when the opt-out action was initiated from a Campaign send.

All Opt-outs: User wants to be removed from all emails from your site

Parameter Description Example
email The user’s email address example@example.com
mode all, blast, template, basic all
optout 1 if the user is opting out
0 if the user is opting back in
1
blast_id Only present if the opt-out was from a campaign/blast. The numeric blast id from which the user clicked Spam or Unsubscribe is returned. 123456
reason The text of the reason provided by the user (if you have set up Opt-out Reasons in your settings).If the user clicked an Unsubscribe button provided by their email application, the reason will be unsubscribe-email.If the user clicked a Spam button provided by their email application, the reason will be spam. I get too much email
list when a user arrives from a campaign email, the list the campaign was mailed to will be returned daily
action describes what action was taken by the user optout

Optout Postback Syntax

Standard postbacks will be formatted like this:

Remote IP:  00.0.0.00
User-Agent: Sailthru Postback
Post Data:
{
   "email" : "example@example.com",
   "mode" : "all",
   "reason" : "spam",
   "optout" : 1,
   "blast_id" : 1234567,
   "list" : "My List Name",
   "action" : "optout",
   "api_key" : "123...",
   "sig" : "abc..."
}

Example (PHP)

If you are using the Sailthru PHP client library, the API call receiveOptoutPost() returns true if the incoming POST data matches that of an opt-out postback.

  $sailthruClient = new Sailthru_Client($api_key, $api_secret);
  if ($sailthruClient->receiveOptoutPost()) {

      switch ($_POST['mode']) {
          case 'all':
              // respond to an opt-out all

          case 'basic':
              // respond to an opt-out basic

          case 'blast':
              // respond to an opt-out blast

          case 'template':
              // respond to a template optout ($_POST['template'] has the name)

          }
      } else {
      header('HTTPS/1.1 403 Forbidden');
  }

List Postbacks

Sailthru also offers a postback when a user unsubscribes from a specific list. You will need to contact your account manager or contact support to have this enabled. The postback return value syntax would be:

Remote IP:  xxx
User-Agent: Sailthru Postback
Post Data:
(
    [sid] => 515...
    [email] => example@example.com
    [page] => oc
    [optout_email] => none
    [lists] => Array
        (
            [List A] => 0
            [List B] => 1
        )

    [action] => update
    [api_key] => 982...
    [sig] => 934...
)

0 indicates the user was removed from that list; 1 indicates they were added to that list.

Hardbounce Postbacks

You can be notified whenever an email hardbounces.

To turn on hardbounce postbacks, set the Hardbounce Postback URL in your Settings.

Sailthru will POST the following parameters:

  • email  – the email address that hardbounced
  • send_idor blast_id  – the identifier for the message that caused the hardbounce

The API key and a hashed signature will also be included in this post.

Top