Postbacks

When a user clicks on an opt-out or verification link, you may want your web server to be notified. For example, if the user verifies an email address, you may need to immediately set the user's status in your database to "verified".

To deal with this situation, you can optionally set up a URI in Sailthru API calls to post data to your server immediately when these events happen, using the shared-secret API authentication.

You can view an audit log of all of your postbacks — this is especially helpful when debugging.

In your postback page, if everything is successful, you should output an HTTP 200 header status code (this is the default behavior of most web platforms/frameworks). If you have a problem, you should emit an HTTP 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.

When creating your template in the template editor, you can set the Verify Postback URI field if the template type is set to "Email Verification". If you leave this field blank, no postback will occur.

Now you need to write the script that processes the postback at that URI. 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 Sailthru API client 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.

Here's an example of a verification postback script in 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('HTTP/1.1 500 Internal Server Error');
          // or whatever other user verification you want to do!
      }
  } else {
      header('HTTP/1.1 403 Forbidden');
  }

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

You can set an optout postback for all optouts via the Settings page. This will apply to all optouts from all Sailthru-powered emails. To turn on optout postbacks, set the Optout Postback URI in your account settings.

Every time someone clicks an optout link, or clicks a button on a confirmed optout page, Sailthru will post to your page. There are three types of optouts: all optouts, template optouts, and list optouts. Depending on the type of optout, Sailthru will post the following parameters:

"All" Optouts: User wants to be removed from all emails from your site.

Blast Optouts User wants to be removed from mass mails only.

Template Optouts: User wants to be removed from a particular type of email (e.g. private message alerts).

The Sailthru API client call receiveOptoutPost() returns true if the incoming POST data matches that of an optout postback.

Here's a skeleton of an optout script in PHP:

  $sailthruClient = new Sailthru_Client($api_key, $api_secret);
  if ($sailthruClient->receiveOptoutPost()) {
      switch ($_POST['mode']) {
          case 'all':
              // respond to an optout all
 
          case 'blast':
              // respond to an optout blast
 
          case 'template':
              // respond to a template optout ($_POST['template'] has the name)
          }
      } else {
      header('HTTP/1.1 403 Forbidden');
  }

You can be notified whenever an email hardbounces. This can be useful to notify the user that there is a problem with his or her email address.

To turn on hardbounce postbacks, set the Hardbounce Postback URI in your account settings.

Sailthru will POST the following parameters:

• email - the email address that is hardbouncing
• either send_id or 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.