https://<subdomain>.sendsmaily.net/api/v2/tracking/events


Query parameters


Parameter
Type
Required

start_at
Date and time
Yes
Events date range filter start date. Accepts UNIX epoch time and ISO 8601 formatted datetime string value.
end_at
Date and time
Yes
Events date range filter end date. Accepts same value types as start_at.
date_field
String

Events date range filter target field. Accepts either created_at (event creation date and time) or logged_at (event process date and time) value. When omitted created_at will be used.
type
List (comma separated)

Event types filter. Accepts comma separated list of values from available event types - message_viewed, unique_message_viewed, link_clicked, unique_link_clicked, message_opened, message_opened_in_client, message_opened_in_country, message_opened_in_os. When omitted all event types are returned.
offset
Integer

Page number, which begins at zero. Offset value is multiplied by value of limit to determine the number of events to return. When omitted zero (0) will be used.
limit
Integer

Number of events per page. When omitted 100 will be used. Can have maximum value of 10000.



Common payload

Each event contains at least these fields.


Field
Type

event_id
UUID
Event's unique identifier.
version
Integer
Event's specification version.
type
String
Event type identifier.
created_at
Date and time
ISO 8601 formatted date and time of event's creation.
logged_at
Date and time
ISO 8601 formatted date and time of event's process.
message_id
UUID
Message unique identifier.
campaign_pk
UUID
Reference to campaign entity.
post_pk
UUID
Reference to campaign's post entity.
contact_pk
UUID
Reference to contact entity.



Events


message_viewed

Emitted when recipient triggers tracking pixel by downloading images of the message.


Along side common payload fields event's payload contains following field(s):

Field
Type

user_agent
String
User-Agent header value provided by viewer's software.
ip_address
IP-address
Public IP-address of the viewer.
source
String
Originating message part. Currently html is the only supported value.
http_referer
String
Referer header value, if any.


Example document:

{
    'event_id': 'f09496ba-b60b-4125-9742-27decdc093fd',
    'version': 1,
    'type': 'message_viewed',
    'created_at': '2017-09-05T17:05:00+00:00',
    'logged_at': '2017-09-05T17:05:10+00:00',
    'message_id': '888f5de4-35bc-4b1a-a5f5-11a14cba02c8',
    'campaign_pk': 'c93bd9b4-2924-47ad-a54b-2c74f373c4b6',
    'post_pk': 'b942e499-5ec0-49ca-9631-8ddf520d73eb',
    'contact_pk': 'fd2a0719-53b6-4c80-a284-bc3d2953f018',
    'user_agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36',
    'ip_address': '1.2.3.4',
    'source': 'html',
    'http_referer': 'http://smaily.com',
}



unique_message_viewed

Emitted when recipient triggers tracking pixel by downloading images of the message for the first time.


Payload for this event is the same as for message_viewed.


Example document:

{
    'event_id': 'f09496ba-b60b-4125-9742-27decdc093fd',
    'version': 1,
    'type': 'unique_message_viewed',
    'created_at': '2017-09-05T17:05:00+00:00',
    'logged_at': '2017-09-05T17:05:10+00:00',
    'message_id': '888f5de4-35bc-4b1a-a5f5-11a14cba02c8',
    'campaign_pk': 'c93bd9b4-2924-47ad-a54b-2c74f373c4b6',
    'post_pk': 'b942e499-5ec0-49ca-9631-8ddf520d73eb',
    'contact_pk': 'fd2a0719-53b6-4c80-a284-bc3d2953f018',
    'user_agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36',
    'ip_address': '1.2.3.4',
    'source': 'html',
    'http_referer': 'http://smaily.com',
}



Emitted when recipient clicks on a link in the message.


Along side common payload fields event's payload contains following field(s):

Field
Type

link_pk
UUID
Reference to link entity.
url
String
URL of the link.
mail_to
String
Email address of the recipient.
user_agent
String
User-Agent header value provided by web browser.
ip_address
IP-address
Public IP-address of the link clicker.
source
String
Originating message part. Currently html is the only supported value.
http_referer
String
Referer header value, if any.


Example document:

{
    'event_id': '1764a5b0-0aaf-4f73-8ae8-3d5bbb9566e9',
    'version': 1,
    'type': 'link_clicked',
    'created_at': '2017-09-05T17:05:00+00:00',
    'logged_at': '2017-09-05T17:05:10+00:00',
    'message_id': '888f5de4-35bc-4b1a-a5f5-11a14cba02c8',
    'campaign_pk': 'c93bd9b4-2924-47ad-a54b-2c74f373c4b6',
    'post_pk': 'b942e499-5ec0-49ca-9631-8ddf520d73eb',
    'contact_pk': 'fd2a0719-53b6-4c80-a284-bc3d2953f018',
    'link_pk': '07b8df24-4b12-451f-b9ed-a4b394dee338',
    'url': 'http://smaily.com/example',
    'mail_to': 'example@smaily.com',
    'user_agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36',
    'ip_address': '1.2.3.4',
    'source': 'html',
    'http_referer': 'http://smaily.com',
}



unique_link_clicked

Emitted when recipient clicks on a link in message for the first time.


Payload for this event is the same as for link_clicked.


Example document:

{
    'event_id': '1764a5b0-0aaf-4f73-8ae8-3d5bbb9566e9',
    'version': 1,
    'type': 'unique_link_clicked',
    'created_at': '2017-09-05T17:05:00+00:00',
    'logged_at': '2017-09-05T17:05:10+00:00',
    'message_id': '888f5de4-35bc-4b1a-a5f5-11a14cba02c8',
    'campaign_pk': 'c93bd9b4-2924-47ad-a54b-2c74f373c4b6',
    'post_pk': 'b942e499-5ec0-49ca-9631-8ddf520d73eb',
    'contact_pk': 'fd2a0719-53b6-4c80-a284-bc3d2953f018',
    'link_pk': '07b8df24-4b12-451f-b9ed-a4b394dee338',
    'url': 'http://smaily.com/example',
    'mail_to': 'example@smaily.com',
    'user_agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36',
    'ip_address': '1.2.3.4',
    'source': 'html',
    'http_referer': 'http://smaily.com',
}



message_opened

Emitted when recipient clicks a link or downloads images in the message for the first time.


Example document:

{
    'event_id': 'ab0e3f21-964f-4329-9f0e-009d22010813',
    'version': 1,
    'type': 'message_opened',
    'created_at': '2017-09-05T17:05:00+00:00',
    'logged_at': '2017-09-05T17:05:10+00:00',
    'message_id': '888f5de4-35bc-4b1a-a5f5-11a14cba02c8',
    'campaign_pk': 'c93bd9b4-2924-47ad-a54b-2c74f373c4b6',
    'post_pk': 'b942e499-5ec0-49ca-9631-8ddf520d73eb',
    'contact_pk': 'fd2a0719-53b6-4c80-a284-bc3d2953f018',
}



message_opened_in_client

Emitted when message is opened in unique email client.


Along side common payload fields event's payload contains following field(s):

Field
Type

client
String
Normalized name of the email client used to open the message.


Example document:

{
    'event_id': '68e851a6-0c56-4995-b120-70beb23470e6',
    'version': 1,
    'type': 'message_opened_in_client',
    'created_at': '2017-09-05T17:05:00+00:00',
    'logged_at': '2017-09-05T17:05:10+00:00',
    'message_id': '888f5de4-35bc-4b1a-a5f5-11a14cba02c8',
    'campaign_pk': 'c93bd9b4-2924-47ad-a54b-2c74f373c4b6',
    'post_pk': 'b942e499-5ec0-49ca-9631-8ddf520d73eb',
    'contact_pk': 'fd2a0719-53b6-4c80-a284-bc3d2953f018',
    'client': 'Outlook 2007-2013',
}



message_opened_in_country

Emitted when message is opened from unique country.


Along side common payload fields event's payload contains following field(s):

Field
Type

country
String
Full name of the country of the open's origin.
country_code
String
ISO Alpha-2 country code of the open's origin.


Example document:

{
    'event_id': '8171e47e-3983-4b3b-a4c3-6466125065fd',
    'version': 1,
    'type': 'message_opened_in_country',
    'created_at': '2017-09-05T17:05:00+00:00',
    'logged_at': '2017-09-05T17:05:10+00:00',
    'message_id': '888f5de4-35bc-4b1a-a5f5-11a14cba02c8',
    'campaign_pk': 'c93bd9b4-2924-47ad-a54b-2c74f373c4b6',
    'post_pk': 'b942e499-5ec0-49ca-9631-8ddf520d73eb',
    'contact_pk': 'fd2a0719-53b6-4c80-a284-bc3d2953f018',
    'country': 'Estonia',
    'country_code': 'EE',
}



message_opened_in_os

Emitted when message is opened in unique operating system.


Along side common payload fields event's payload contains following field(s):

Field
Type

device_type
String
Operating system's device type. Currently desktop and mobile values are supported.
os
String
Name of the operating system of the open's origin.


Example document:

{
    'event_id': 'f341b106-8a86-4922-92e7-54a432ac6a43',
    'version': 1,
    'type': 'message_opened_in_os',
    'created_at': '2017-09-05T17:05:00+00:00',
    'logged_at': '2017-09-05T17:05:10+00:00',
    'message_id': '888f5de4-35bc-4b1a-a5f5-11a14cba02c8',
    'campaign_pk': 'c93bd9b4-2924-47ad-a54b-2c74f373c4b6',
    'post_pk': 'b942e499-5ec0-49ca-9631-8ddf520d73eb',
    'contact_pk': 'fd2a0719-53b6-4c80-a284-bc3d2953f018',
    'device_type': 'desktop',
    'os': 'macOS 10.12',
}