Callbacks (Transactional Only)

Please note that this API functionality has been deprecated in favour of our new Webhook API. Visit our Transactional API Migration page to learn more.

Callbacks (Transactional Only)

Callbacks allow our system to automatically notify your server when certain events happen. When a callback is invoked, it sends a message with information about the event to a specified URL.

To enable callbacks on your transactional emails:

Log into your transactional email dashboard.
Click the Settings cog icon at the bottom of the left-hand navigation bar.
Check the checkbox for Sending callbacks. The properties window will open on the right.
Check the checkbox to Enable Callbacks.
Enter the URL you want the callbacks posted to in the ‘Post to URL’ field.
Check the checkboxes for the types of callbacks you want to receive (e.g. sent, delivered, failed etc.).

Technical Details of Callback Requests Made

Event Types:

Sent: When we successfully send a transactional mail
Failed: When we failed to send a transactional mail
Bounced: When we successfully sent a transactional mail, but the receiving server did not accept it
Opened: When a contact opens a transactional mail that was delivered to them
Clicked: When a contact clicks on a link inside a transactional mail that was delivered to them
Unsubscribe: When a contact unsubscribes from receiving transactional mail from you
Resubscribe: When a contact was unsubscribed, but they changed their mind and resubscribed to receive transactional mail from you

Sample Callback Request

All of the above requests will be a Request made to the URL that you’ve provided. Each request will contain a JSON object with the following information:

"event": {
   "event_id" : ,
   "event_date" : ,
   "event_type" : ,
   "email_to" : ,
   "group_name" : ,
   "custom_headers" : ,
   "trans_id" : 
}

All of the variables we send are contained inside an event Object. You can see an example further down. The variables that are the same for all events are as follows:

event_id – Unique identifier for the event
event_date – Unix Timestamp that the event happened
event_type – One of the following: “sent”, “failed”, “open”, “click”, “unsubscribe”, “resubscribe”, “bounced”
email_to – Email address that the transaction was sent to
group_name – Transactional group name this mail was assigned to
custom_headers – Any custom headers provided
trans_id – Unique identifier for the transaction

There are some custom variables that will only be included for certain events they are as follows:

Sent: We include subject Which is the subject of the transactional mail
Bounced: We include the following:
- bounced_email Instead of email_to which is the email address that bounced
- bounced_received_date The date the bounce was recieved
- bounce_type The type of bounce. This can be either Hard or Soft
- trans_bcontent_complete_mime The entire mime that was received from the bounce server

Example code includes:

Sent / failed / opened / unsubscribe / resubscribe:

"event": {
   "event_id" : "123",
   "event_date" : "1598565600",
   "event_type" : "<sent/failed/opened/unsubscribe/resubscribe>", // Will only contain one of these
   "email_to" : "[email protected]",
   "group_name" : "Test Group",
   "custom_headers" : "Content-Type: application/json",
   "trans_id" : 321
}

Bounced:

"event": {
   "event_id" : "123",
   "event_date" : "1598565600",
   "event_type" : "bounced",
   "bounced_email" : "[email protected]",
   "bounced_received_date" : "1598565650",
   "bounce_type" : "hard",
   "bounce_reason" : "Policy-Related",
   "trans_bcontent_complete_mime" : "<Big Mime Here>",
   "group_id" : 123,
   "custom_headers" : "Content-Type: application/json",
   "trans_id" : 321
}

Clicked:

"event": {
   "event_id" : "123",
   "event_date" : "1598565600",
   "event_type" : "clicked",
   "unique_open" : "yes"
   "email_to" : "[email protected]",
   "group_name" : "Test Group",
   "custom_headers" : "Content-Type: application/json",
   "trans_id" : 321,
   "link" : "<a target="_blank" class="c-link" data-stringify-link="http://example.com/something" delay="150" data-sk="tooltip_parent" href="http://example.com/something" rel="noopener noreferrer">http://example.com/something"
}