This shows you the differences between two versions of the page.
|
api-email-reports [2017/02/03 14:01] ben [Endpoint] |
api-email-reports [2017/07/26 08:24] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== API Email Report Endpoints ====== | ||
| - | The Email Report Endpoints are used to get Reporting data regarding an Email back from Sentori. | ||
| - | |||
| - | ===== Email KPI ===== | ||
| - | |||
| - | This Endpoint is used to get the Emails KPI, you can also restrict it to a specific Iteration of the Email. | ||
| - | |||
| - | ==== Endpoint ==== | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/kpi/{EmailExternalID}/</nowiki>| | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/kpi/{EmailExternalID}/{Iteration}/</nowiki>| | ||
| - | |Method| GET | | ||
| - | |||
| - | ==== Response ==== | ||
| - | |||
| - | |Field|Type|Description| | ||
| - | |Sent|int|Number of Contacts this Email was Sent to.| | ||
| - | |Bounced|int|Number of Emails that bounced.| | ||
| - | |Opens|int|Number of Contacts who opened this Email.| | ||
| - | |UniqueClickers|int|Number of Contacts who clicked a link in this Email.| | ||
| - | |TotalClicks|int|Total number of clicks on links in this Email.| | ||
| - | |SocialShares|int|Number of times this Email was shared on Social Networks| | ||
| - | |SocialKpi|object|Contains a breakdown of the number of times this Email was shared on Social Networks.| | ||
| - | |Unsubscribes|int|The number of Contacts who Unsubscribed.| | ||
| - | |AbuseComplaints|int|The number of spam complains generated by this Email.| | ||
| - | |||
| - | |Example|<code javascript>{ | ||
| - | "Sent":100, | ||
| - | "Bounced":10, | ||
| - | "Opens":25, | ||
| - | "UniqueClickers":20, | ||
| - | "TotalClicks":23, | ||
| - | "SocialShares":0, | ||
| - | "SocialKpi": { | ||
| - | "GooglePlusOnes":0, | ||
| - | "LinkedInShares":0, | ||
| - | "Tweets":0, | ||
| - | "FacebookLikes":0 | ||
| - | }, | ||
| - | "Unsubscribes":1, | ||
| - | "AbuseComplaints":4 | ||
| - | }</code>| | ||
| - | |||
| - | ===== Abuse Complaints ===== | ||
| - | |||
| - | This Endpoint is used to get the Contacts who complained that the Email was spam. | ||
| - | |||
| - | ==== Endpoint ==== | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/abuse/{EmailExternalID}/</nowiki>| | ||
| - | |Method| GET | | ||
| - | |||
| - | ==== Response ==== | ||
| - | |||
| - | The response is a JSON array containing Email Addresses of Contacts and the time of the Abuse Complaint. | ||
| - | |||
| - | |Field|Type|Description| | ||
| - | |EmailAddress|string|Email Address of the Contact who reported this Email as spam.| | ||
| - | |Timestamp|datetime|Time that the Contact complained about this Email.| | ||
| - | |||
| - | |Example|<code javascript>[{ | ||
| - | "EmailAddress":"joe@example.sentoriapp.com", | ||
| - | "Timestamp":"2015-01-01T00:00:00.000" | ||
| - | }]</code>| | ||
| - | |||
| - | ===== Bounces ===== | ||
| - | |||
| - | This Endpoint is used to get the Contacts whose Email Addresses bounced when they where sent the Email. It can be restricted to a specific Iteration. | ||
| - | |||
| - | ==== Endpoint ==== | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/bounced/{EmailExternalID}/</nowiki>| | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/bounced/{EmailExternalID}/{Iteration}/</nowiki>| | ||
| - | |Method| GET | | ||
| - | |||
| - | ==== Response ==== | ||
| - | |||
| - | The response is a JSON array containing Email Addresses of Contacts and the time of the bounce. | ||
| - | |||
| - | |Field|Type|Description| | ||
| - | |EmailAddress|string|Email Address of the Contact who bounced.| | ||
| - | |Timestamp|datetime|Time that the Email bounced.| | ||
| - | |||
| - | |Example|<code javascript>[{ | ||
| - | "EmailAddress":"joe@example.sentoriapp.com", | ||
| - | "Timestamp":"2015-01-01T00:00:00.000" | ||
| - | }]</code>| | ||
| - | |||
| - | ===== Clickers ===== | ||
| - | |||
| - | This Endpoint is used to get the Contacts who clicked at least one Link in the Email. It can be restricted to a specific Iteration. | ||
| - | |||
| - | ==== Endpoint ==== | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/clicks/{EmailExternalID}/</nowiki>| | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/clicks/{EmailExternalID}/{Iteration}/</nowiki>| | ||
| - | |Method| GET | | ||
| - | |||
| - | ==== Response ==== | ||
| - | |||
| - | The response is a JSON array containing Email Addresses of Contacts and the time of the first click. | ||
| - | |||
| - | |Field|Type|Description| | ||
| - | |EmailAddress|string|Email Address of the Contact who clicked.| | ||
| - | |Timestamp|datetime|Time of the click.| | ||
| - | |||
| - | |Example|<code javascript>[{ | ||
| - | "EmailAddress":"joe@example.sentoriapp.com", | ||
| - | "Timestamp":"2015-01-01T00:00:00.000" | ||
| - | }]</code>| | ||
| - | |||
| - | |||
| - | ===== Link Clickers ===== | ||
| - | |||
| - | This Endpoint is used to get details of Contacts who clicked through to a particular link in an Email and includes when each made their first click of that link. | ||
| - | |||
| - | If the exact same link URL appears multiple times within the Email, for example a link to your homepage is set on your logo as well as in your footer, then they'll be considered the same link. | ||
| - | |||
| - | |||
| - | ==== Endpoint ==== | ||
| - | |||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/linkclickers/{EmailExternalID}/{Base64EncodedUrl}/</nowiki>| | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/linkclickers/{EmailExternalID}/{Base64EncodedUrl}/{Iteration}/</nowiki>| | ||
| - | |Method| GET | | ||
| - | |||
| - | |||
| - | Examples: | ||
| - | |||
| - | <nowiki>GET https://api.sentoriapp.com/v2.0/email/linkclickers/ABCD1234/aHR0cDovL215d2Vic2l0ZS5jb20v/</nowiki> | ||
| - | |||
| - | <nowiki>GET https://api.sentoriapp.com/v2.0/email/linkclickers/ABCD1234/aHR0cDovL215d2Vic2l0ZS5jb20v/3</nowiki> | ||
| - | |||
| - | |||
| - | ==== Request ==== | ||
| - | |||
| - | |EmailExternalID|The External ID of the Email, e.g. "ABCD1234". Found by going to Edit Properties from the cog menu of an Email.| | ||
| - | |Base64EncodedUrl|The URL of the link encoded using [[https://en.wikipedia.org/wiki/Base64|base64]]. "<nowiki>http://mywebsite.com/</nowiki>" would therefore be "aHR0cDovL215d2Vic2l0ZS5jb20v".| | ||
| - | |Iteration|Optional. If provided, restricts Clicks to those made in a particular send of the Email.| | ||
| - | |||
| - | |||
| - | ==== Response ==== | ||
| - | |||
| - | The response is a JSON array containing Contacts' SystemIDs, Email Addresses and the date and time of their first click of the link. | ||
| - | |||
| - | |Field|Type|Description| | ||
| - | |SystemID|integer|Sentori SystemID of the Contact.| | ||
| - | |EmailAddress|string|Email Address of the Contact.| | ||
| - | |FirstClick|datetime|Date and time (in UTC) when the Contact first clicked the link.| | ||
| - | |||
| - | |Example|<code javascript> | ||
| - | [ | ||
| - | { | ||
| - | "SystemID" : 1, | ||
| - | "EmailAddress" : "contact1@sentori.co.uk", | ||
| - | "FirstClick" : "2013-02-21T17:11:57.53" | ||
| - | }, | ||
| - | { | ||
| - | "SystemID" : 2, | ||
| - | "EmailAddress" : "contact2@sentori.co.uk", | ||
| - | "FirstClick" : "2013-02-21T17:11:57.53" | ||
| - | } | ||
| - | ] | ||
| - | </code>| | ||
| - | |||
| - | |||
| - | ===== Opens ===== | ||
| - | |||
| - | This Endpoint is used to get the Contacts who have opened the Email. It can be restricted to a specific Iteration. | ||
| - | |||
| - | ==== Endpoint ==== | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/opens/{EmailExternalID}/</nowiki>| | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/opens/{EmailExternalID}/{Iteration}/</nowiki>| | ||
| - | |Method| GET | | ||
| - | |||
| - | ==== Response ==== | ||
| - | |||
| - | The response is a JSON array containing Email Addresses of Contacts and the time of the first open. | ||
| - | |||
| - | |Field|Type|Description| | ||
| - | |EmailAddress|string|Email Address of the Contact who opened the Email.| | ||
| - | |Timestamp|datetime|Time of the open.| | ||
| - | |||
| - | |Example|<code javascript>[{ | ||
| - | "EmailAddress":"joe@example.sentoriapp.com", | ||
| - | "Timestamp":"2015-01-01T00:00:00.000" | ||
| - | }]</code>| | ||
| - | |||
| - | |||
| - | ===== Social Shares ===== | ||
| - | |||
| - | This Endpoint is used to get the Contacts who have shared the Email on at least one social network. It can be restricted to a specific Iteration. | ||
| - | |||
| - | ==== Endpoint ==== | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/socialsharers/{EmailExternalID}/</nowiki>| | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/socialsharers/{EmailExternalID}/{Iteration}/</nowiki>| | ||
| - | |Method| GET | | ||
| - | |||
| - | ==== Response ==== | ||
| - | |||
| - | The response is a JSON array containing Email Addresses of Contacts and the time of the first social share. | ||
| - | |||
| - | |Field|Type|Description| | ||
| - | |EmailAddress|string|Email Address of the Contact who shared the Email on a Social Network.| | ||
| - | |Timestamp|datetime|Time of the share.| | ||
| - | |||
| - | |Example|<code javascript>[{ | ||
| - | "EmailAddress":"joe@example.sentoriapp.com", | ||
| - | "Timestamp":"2015-01-01T00:00:00.000" | ||
| - | }]</code>| | ||
| - | |||
| - | ===== Unsubscribes ===== | ||
| - | |||
| - | This Endpoint is used to get the Contacts who have unsubscribed from Emails using the unsubscribe Link in this Email. It can be restricted to a specific Iteration. | ||
| - | |||
| - | ==== Endpoint ==== | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/unsubscribes/EmailExternalID/</nowiki>| | ||
| - | |URI| <nowiki>https://api.sentoriapp.com/v2.0/email/unsubscribes/EmailExternalID/Iteration/</nowiki>| | ||
| - | |Method| GET | | ||
| - | |||
| - | ==== Response ==== | ||
| - | |||
| - | The response is a JSON array containing Email Addresses of Contacts and the time of the unsubscribe. | ||
| - | |||
| - | |Field|Type|Description| | ||
| - | |EmailAddress|string|Email Address of the Contact who unsubscribed.| | ||
| - | |Timestamp|datetime|Time of the unsubscribe.| | ||
| - | |||
| - | |Example|<code javascript>[{ | ||
| - | "EmailAddress":"joe@example.sentoriapp.com", | ||
| - | "Timestamp":"2015-01-01T00:00:00.000" | ||
| - | }]</code>| | ||