API Postbacks

Contents

Verify Postbacks
Opt-out Postbacks
- Opt-Out Types and Parameters
Update Postbacks
Hardbounce Postbacks

API communication typically resembles the following: a call is sent, and information is returned. However, APIs do not require a call to send data. Using API postbacks, the Sailthru API can send information in response to an event, for example, when a user opts out or an email hardbounces. 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. You'll need to configure a postback URL on your server, accessible to Sailthru over the internet. You can optionally supply a different URL for each postback type. For hardbounce and optout postbacks, you will need to provide these URLs in your Settings. For each postback, Sailthru makes a POST call to the supplied postback URL. Data is URL encoded, so it would appear similar to this example request body:

email=user@example.com&mode=template&optout=1&action=optout&api_key=e242166d82524c7c7ed09792a2fcac6c&sig=3888248fda30685ca4d791e220f413e5

For security purposes, you will need to confirm that the api_key parameter matches your Sailthru API key, and that the sig parameter matches the expected sig value (a hash of your API key and all parameter values for the postback call, when they are concatenated and arranged in a particular order). Most of the available client libraries have functions that handle the postback data, including this sig-verification process.

For specific examples, please see the documentation for the specific API client library you are using. If you need to calculate a sig manually, see the API Technical Details page for more information. If everything is successful in your processing of the postback, you should output an HTTPS 200 header status code. If a problem occurs, 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. For more information, see API Response Errors.

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

Example values returned:

Post Data:
Array
(
[email] => example@sailthru.com
[send_id] => WFmfCby1nMkoi0ZI
[action] => verify
[api_key] => 2479370a3ed840cf184df1f5f00f32f1
[sig] => 3d5b94ae50d6e65fbc94cc93326feffb
)

For those Sailthru libraries that contain the receiveVerifyPost(), this function 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(<a href="http://www.php.net/array">array</a>(':email' => $_POST['email']))) {

          <a href="http://www.php.net/header" rel="nofollow">header</a>('HTTPS/1.1 500 Internal Server Error');
          // or whatever other user verification you want to do!
      }
  } else {
      <a href="http://www.php.net/header" rel="nofollow">header</a>('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 API & Postbacks Settings page. This will apply to all opt-outs from Sailthru-powered emails. Every time a user 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 two 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. If a user is opted out using this option, their User Profile will show their status as Optout (All).

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. If a user is opted out using this option, their User Profile will show their status as Optout (Marketing).

When an opt-out occurs, Sailthru will post the following parameters, with the mode parameter representing one of the above opt-out types. The POST call made to their endpoint is URL encoded, the actual data payload of a postback is array data. Note: 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`, `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`	Only set for some hosted email applications when the user clicks the Spam or Unsubscribe link (if you have set up Opt-out Reasons in your settings). `unsubscribe-email`: The user clicked the unsubscribe link provided by their ISP and the ISP sent the information back to Sailthru. `spam`: The user clicked the Spam button provided by other email applications. `api`: The user clicked an Unsubscribe link on a Sailthru Hosted Page.	`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`

Example Optout Postback Data

Post Data:
Array
(
 [email] => example@sailthru.com
 [mode] => basic
 [optout] => 1
 [action] => optout
 [api_key] => 2479370a3ed840cf184df1f5f00f32f1
 [sig] => 3d5b94ae50d6e65fbc94cc93326feffb
)

Example (PHP) If you are using the Sailthru PHP client library, the function 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 {
      <a href="http://www.php.net/header" rel="nofollow">header</a>('HTTPS/1.1 403 Forbidden');
  }

Update Postbacks

Sailthru also offers a postback when a user changes their list subscriptions or custom field (a.k.a. var) values on a User Management Hosted Page. You will need to contact your Customer Success representative or Support to have this enabled. The postback return value syntax would be:

Post Data:
Array:
(
    [sid] => 515...
    [email] => example@example.com
    [page] => oc
    [optout_email] => none
    [lists] => Array
        (
            [List A] => 0
            [List B] => 1
        )
    [vars] => Array
        (
            [Var A] => new value
            [Var B] => new value
        )
    [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 API & Postbacks Settings page. 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. Example hardbounce postback data:

Post Data:
Array
(
    [email] => blashsdsd@dfsdf.com
    [send_id] => WFQKQW5K3LBgi0mk
    [action] => hardbounce
    [api_key] => 6b805755ce5a23e3c0459aaa598efc56
    [sig] => 13b3987b656c7771fcac92982fdfb331
)