====== 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>|