This is an old revision of the document!
When a Contact unsubscribes, you can have Sentori pass this information on to an external system, such as your CRM system, to keep everything in sync.
To use this feature, set the Contact Unsubscribe Webhook for your account by signing in to Sentori then going to the Settings menu and choosing API.
This is how Sentori structures its request to your external system when a Contact unsubscribes:
Content-Type | application/json |
AccountExternalID | The External ID of the Account the Contact has unsubscribed from. |
EmailAddress | The email address of the Contact that has unsubscribed. |
Type | The string “unsubscribe”. |
Date | The date and time when the unsubscribe occurred. Formatted to ISO 8601, e.g. “2016-02-01T14:12:59.1230000Z” |
vhash | A hashed value used to confirm it's a genuine notification from Sentori. |
Description | A human-readable message containing the other values. |
POST [your webhook url] HTTP/1.1 Content-Type: application/json User-Agent: Sentori API Content-Length: 314 { "AccountExternalID":"1234ABCD", "EmailAddress":"user@example.com", "Type":"unsubscribe", "Date":"2016-02-01T14:12:59.1230000Z", "vhash":"F88EA6387F4CF9F258521444C34FEB526DF66A55", "Description":"\"user@example.com\" logged \"unsubscribe\" Event at \"Mon 01 Feb 2016 14:12 UTC\"." }
To confirm the request isn't from another system impersonating Sentori, perform the following operation.
If the result matches the vhash value in the request, it's genuine.
Here's the example above being checked using C# code:
The API Key of this Sentori Account is “20011111-1111-1111-1111-111111111200”.
string values = "1234ABCD" + "user@example.com" + "unsubscribe" + "2016-02-01T14:12:59.1230000Z" + "20011111-1111-1111-1111-111111111200"; byte[] bytes = System.Text.Encoding.Default.GetBytes(values); System.Security.Cryptography.SHA1Managed sha1 = new System.Security.Cryptography.SHA1Managed(); string checkHash = BitConverter.ToString(sha1.ComputeHash(bytes)); checkHash = checkHash.Replace("-", string.Empty); // Output is "true" if genuine, "false" if not. Console.WriteLine("Is genuine? " + ("F88EA6387F4CF9F258521444C34FEB526DF66A55" == checkHash));
When a bounce occurs as a result of attempting to send an email to a Contact, you can have Sentori pass this information on to an external system, such as your CRM system, to keep everything in sync.
To use this feature, set the Email Bounce Webhook for your account by signing in to Sentori then going to the Settings menu and choosing API.
Depending on the information contained in a bounce and whether any previous bounces have occurred, Sentori will either log the bounce and immediately set the Contact to “Bad” (by setting their “Bad Email Address” Field to “Yes”) or just log the bounce which goes towards a Contact's overall bounce count.
Contacts are marked as “Bad” when their “Bad Email Address” boolean Field is set to “True” (or “Yes”). Sentori excludes those Contacts from sends.
This is how Sentori structures its request to your external system when a bounce occurs:
Content-Type | application/json |
AccountExternalID | The External ID of the Account the bounce relates to. |
EmailAddress | The email address of the Contact the bounce relates to. |
ContactMarkedBad | A true or false value indicating whether this bounce resulted in the Contact being marked as “Bad” or not. |
BounceMessage | The bounce message received by Sentori. |
Date | The date and time when this bounce message was received by Sentori. Formatted to ISO 8601, e.g. “2016-02-01T14:12:59.1230000Z” |
vhash | A hashed value used to confirm it's a genuine notification from Sentori. |
Description | A human-readable message containing the other values. This will change slightly to reflect whether ContactMarkedBad is true or false. |
POST [your webhook url] HTTP/1.1 Content-Type: application/json User-Agent: Sentori API Content-Length: 455 { "AccountExternalID":"1234ABCD", "EmailAddress":"user@example.com", "ContactMarkedBad":true, "BounceMessage":"550 Invalid Recipient user@example.com", "Date":"2016-02-01T14:12:59.1230000Z", "vhash":"7D1CB46C9EAACEE2880F717B0088ACB25AEE3B3E", "Description":"Bounce logged for email address \"user@example.com\" at "Tue 23 Feb 2016 11:58 UTC".\\n\\nThe Contact has been marked as having a Bad Email Address as a result of this Bounce.\\n\\n\Bounce Message: \"550 Invalid Recipient user@example.com\"" }
To confirm the request isn't from another system impersonating Sentori, perform the following operation.
If the result matches the vhash value in the request, it's genuine.
Here's the example above being checked using C# code:
The API Key of this Sentori Account is “20011111-1111-1111-1111-111111111200”.
string values = "1234ABCD" + "user@example.com" + true.ToString().ToLower() + "550 Invalid Recipient user@example.com" + "2016-02-01T14:12:59.1230000Z" + "20011111-1111-1111-1111-111111111200"; byte[] bytes = System.Text.Encoding.Default.GetBytes(values); System.Security.Cryptography.SHA1Managed sha1 = new System.Security.Cryptography.SHA1Managed(); string checkHash = BitConverter.ToString(sha1.ComputeHash(bytes)); checkHash = checkHash.Replace("-", string.Empty); // Output is "true" if genuine, "false" if not. Console.WriteLine("Is genuine? " + ("7D1CB46C9EAACEE2880F717B0088ACB25AEE3B3E" == checkHash));