Webhook

Event Notification System

The Kasplo Event Notification System can notify you about events that you want to monitor, including:

  • Clicks
  • Opens
  • Unsubscribes
  • Spam Complaints
  • Bounces
  • Delivery Attempts

The notifications can take a number of forms, including having Kasplo post data or get data to an HTTP URL that you specify

Types of Events

There are multiple kinds of events in the Kasplo system that you can access or be notified of. This document gives an overview of each kind of event and how they relate.

Note: Realtime Webhook events will be delayed in 30 seconds.

Spam Complaint Events

When someone clicks on a “this is spam” link at an ISP that supports feedback loops, and a feedback loop notification is sent to Kasplo, a spam complaint event is created.

This event occurs so that you can remove the address that generated the complaint from your database or stop sending to it. You can also use this event to maintain statistical information on the number of spam complaints created by each campaign. Continuing to send to an address that has complained about spam can have a negative effect on your deliverability.

scomp

Field Description Example Value
event_type The type of event (scomp). scomp
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid For the most recent bounce in the run: The internal identifier for the send. t9920110705
click_tracking_id The click tracking ID is specified using the X-Kasplo-Click-Tracking-IDheader and can be used to trace an event back to a specific message. 1927393

Click and Open Tracking Events

If you are using Kasplo's click and open tracking, then a click or open event will be created whenever someone loads images in an email message or clicks on a link in it.

engine_click

Field Description Example Value
event_type The type of event (engine_click). engine_click
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid For the most recent bounce in the run: The internal identifier for the send. t9920110705
click_url The URL of the link that was clicked on. http://www.example.com
click_tracking_id The click tracking ID is specified using the X-Kasplo-Click-Tracking-ID header and can be used to trace an event back to a specific message. 1927393
engine_ip The IP address that generated the click 1.2.3.4
user_agent The user agent that generated the click. Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.89 Safari/537.36

Unsubscribe Events

Kasplo Engine can process unsubscribe links via two mechanisms:

  1. When you insert a Kasplo's unsubscribe link, Kasplo processes it.
  2. When you do not include a List-Unsubscribe header, Kasplo engine automatically inserts one for you and processes it.

When someone unsubscribes using either of the above mechanisms, an engine_unsub event will be created.

Example Unsubscribe - HTML Code


                                <a href="##unsubscribetag##http://www.example.com/">Unsubscribe</a>
                                    

##unsubscribetag##http://www.example.com/

:

engine_unsub

Field Description Example Value
event_type The type of event (engine_unsub). engine_unsub
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid For the most recent bounce in the run: The internal identifier for the send. t9920110705
click_url The URL of the destination unsubscribe link. For unsubscribes that occur as a result of the List-Unsubscribe header, this value will be blank. http://www.example.com/unsub.php
click_tracking_id The click tracking ID is specified using the X-Kasplo-Click-Tracking-IDheader and can be used to trace an event back to a specific message. 1927393

Sample API

API URL: https://api.kasplo.com/v1/webhook

Content/Type: application/json

Type: POST [or] GET

Request body:

Sample Reponse


                                {
                                    status:'OK'
                                  }
                                  (or)
                                  {
                                    status:200
                                  }  
                            

Continuing to send to an address that has unsubscribed can negatively impact your deliverability.

Delivery Events

A delivery event represents the attempted delivery of a message through SMTP or to a local mailbox. In the case of an SMTP delivery, this shows whether the remote SMTP server accepted or rejected the message or if the delivery attempt was throttled.

When a message delivery fails bounce event can also be created.

Delivery events can be logged using the delivery_attempt event type described below. Alternatively, delivery events can be viewed with the hvmail_report

delivery_attempt Event

Field Description Example Value
event_type The type of event (delivery_attempt). delivery_attempt
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid The internal identifier for the send. t9920110705
click_tracking_id The click tracking ID is specified using the X-Kasplo-Click-Tracking-ID header and can be used to trace an event back to a specific message. 1927393
timestamp The time that the bounce happened, in seconds past the Unix epoch. 1317305252.08338
status Result of this delivery attempt. Can be success, failure, failure_toolong, deferral or connmaxout. success
is_retry 0 if this is the first delivery attempt and 1 otherwise. 0
injected_time The time that the message was injected into Kasplo’s queue, in seconds past the Unix epoch. 1490817966
message The success, failure, or deferral message for this delivery attempt. 207.99.125.72 accepted message./Remote host said: 250 ok 1490817966 qp 13613/
outmtaid_ip The outgoing IP address used for this delivery attempt (see note below). 127.0.0.1
from_address The first email address in the From header as it was originally injected into Kasplo. [email protected].com

Headers

  1. Default Header
  2. By default X-Kasplo-Click-Tracking-ID header will be received in all the events.

  3. Custom Header
  4. Custom Header can be passed along with X-Kasplo-Click-Tracking-ID , which will be received only in delivery events.

There are multiple methods that can be used to deliver events to your application.

Event Delivery Methods

There are multiple methods that can be used to deliver events to your application.

In most cases, a single method that’s described on this page would be selected, and used for all events. However, you also have the option to have events for different Mail Classes delivered to different destinations.Mail Class could be delivered to a HTTP server.

There is a delay between when an event occurs and when it gets delivered to the configured destination. When both your Kasplo server, and the destination service are under low load, this delay is on the order of one minute. The delay can increase if either end is under high load.

HTTP POST

When an event occurs, Kasplo can make an HTTP POST request to a URL that you specify.

If the use_json_for_http_post option is true:

The POST will have a Content-Type of application/json and contain a JSON-encoded object representing the event’s data.

To indicate successful receipt of the event your application must return a 2xx success HTTP status code, like 200 or OK. Otherwise the event will be re-queued for later transmission.

HTTP GET

When an event occurs, Kasplo can make an HTTP GET request to a URL that you specify.

If the use_json_for_http_post option is true:

The GET will have a Content-Type of application/json and contain a JSON-encoded object representing the event’s data.

To indicate successful receipt of the event your application must return a 2xx success HTTP status code, like 200 or OK. Otherwise the event will be re-queued for later transmission.