API Postbacks
Contents
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
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.
Example Optout Postback Data
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).
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).
|
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 |
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_id
orblast_id
- the identifier for the message that caused the hardbounce
Post Data:
Array
(
[email] => blashsdsd@dfsdf.com
[send_id] => WFQKQW5K3LBgi0mk
[action] => hardbounce
[api_key] => 6b805755ce5a23e3c0459aaa598efc56
[sig] => 13b3987b656c7771fcac92982fdfb331
)