API 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 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 Engage by 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, the system 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 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.

AWS API Gateway API Execute URLs such as https://x.execute-api.x.amazonaws.com/... are not supported. To receive these postbacks, first set up a regional or edge-optimized API Gateway with a custom domain name. AWS documentation with more information can be found here: https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html

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 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 Engage by 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, the system 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, the system 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.

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

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 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

Engage by 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. Marigold Enagage by 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
)