Litmus Real-time Callbacks

TIP

Access to our APIs is evaluated on a case-by-case basis. To find out if your use case is one that we support feel free to get in touch with the details of your project. partners@litmus.com

Using Amazon SNS, Email Analytics provides an option to subscribe to a campaign and receive near real-time callbacks for each open. Note: In order to use this method you will need to be able to handle the volume of HTTP requests that will be generated.

Currently, customers with access to the Email Analytics API are permitted to have 1 Endpoint configured for the real-time callback service at a time.

Configure Endpoint

POST https://analytics-api.litmus.com/api/v1/Campaigns/ConfigureNotificationEndpoint

In order to fully configure the Endpoint you must:

1. Make a POST call to the ConfigureNotificationEndpoint endpoint.
2. Subscribe a campaign and record a hit.
3. Confirm the initial confirmation POST notification from Amazon. (You will need to confirm receipt of this in order to receive future POST requests. See the Amazon Documenation for how to do this properly.)

In order to Subscribe a campaign to your Notification Endpoint please see Subscribe Campaign.

Body parameters	Description
Endpoint	REQUIRED string Set your Notification Endpoint here

Updating your endpoint

If you want to update the endpoint you currently have configured, you must make a new POST call to the ConfigureNotificationEndpoint endpoin and re-do the above steps to confirm the endpoint. This will replace the currently configured notification endpoint.

Examples

cURL

curl -X POST\
  -d '{ "Endpoint" : "http://some-url-you-host" }'\
  -u apikey:password\
  -H "Content-type: application/json"\
  https://analytics-api.litmus.com/api/v1/Campaigns/ConfigureNotificationEndpoint

Result Format

204 No Content

No response body

Subscribe Campaign

PUT https://analytics-api.litmus.com/api/v1/Campaigns/{guid}/Subscribe

To Subscribe a campaign to your notification endpoint, make a PUT request to the Subscribe endpoint.

After subscribing a campaign, when a new hit is recorded it will be sent as a notification to your endpoint.

Examples

cURL

curl -X PUT\
  -u apikey:password\
  -H "Content-type: application/json"\
  https://analytics-api.litmus.com/api/v1/Campaigns/{guid}/Subscribe

Result Format

204 No Content

No response body

Unsubscribe Campaign

PUT https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/UnSubscribe

To Unsubscribe a campaign from your notification endpoint, make a PUT request to the UnSubscribe endpoint.

After unsubscribing a campaign, Email Analytics will no longer send a notification to your endpoint when a hit is recorded.

Examples

cURL

curl -X PUT\
  -u apikey:password\
  -H "Content-type: application/json"\
  https://analytics-api.litmus.com/api/v1/Campaigns/{guid}/UnSubscribe

Result Format

200 OK

No response body

Example of Notification

Here is an example of what a notification will look like once you have configured your endpoint and recorded a hit.

{ 
  "Type" : "Notification", 
  "MessageId" : "13a9afd1-57b5-5c1c-80e4-f7a86d76c646", 
  "TopicArn" : "arn:aws:sns:us-east-1:705477198468:ea_account_production_87", 
  "Message" : "{\"activity_type\":\"Read\",\"campaign_guid\":\"rykxueap\",\"custom_id\":\"\",\"custom_data\":\"[UNIQUE]\",\"custom_type\":\"\",\"lat\":\"34.0007\",\"long\":\"-81.0348\",\"city\":\"\",\"region\":\"South Carolina\",\"country\":\"United States\",\"referrer\":\"\",\"user_agent\":\"Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)\",\"created_at\":\"2021-01-13T18:13:26\",\"mail_client\":\"Gmail\",\"mail_client_specific\":\"Via Gmail's Image Cache\",\"rendering_engine\":\"Webkit\",\"platform\":\"webmail\",\"read_category\":\"GlancedOrUnread\",\"read_seconds\":0}", 
  "Timestamp" : "2021-01-13T18:14:27.040Z", 
  "SignatureVersion" : "1", 
  "Signature" : "nLMmLBFsz9Ye+7IsHUQsr32gnrZl9vc+B6Ptbh0lrpTEmNg+tCa6JrTANcn21te9CVbwt9Tqg9KFUl08r2bSk2EgzEwCOkzqvxKWhIHL6hDePmNmv6gqRO+U6Ko+wRFhbs7y7+vvCc4Ngyf/ivvaO84I8iecE9GAwLzZT+H3/d0CP4hVskvuBDVHUpqwV4IIQJm9qTzHNoL2LO7Be9HIBD03Ck2W9TRj9oaTcWZc5ySu2RJDL7RieIX6UsCPAVX+vSiWsQ0rnn6q03I0P1k/iM5mtsD7M2manYehuS2gYET8y9pKN2tvC8BREPmvx0cCXTVAFqO51xh9dpM5JvHDiQ==", 
  "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-010a507c1833636cd94bdb98bd93083a.pem", 
  "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:705477198468:ea_account_production_87:9ad5896f-f038-4bc4-98ba-9b9f4659b1b2" 
}