https://<subdomain>.sendsmaily.net/api/v2/delivery/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_enqueued, message_delivered, message_bounced, message_reported, message_global_bounced, message_forwarded. 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
Unique message 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_enqueued

Emitted when message is enqueued for delivery in MTA.


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

Field
Type

mail_to
String
Email address of the message recipient.


Example document:

{
    'event_id': 'f9e7f5df-3eb1-44e1-9fd7-d0914a0830ea',
    'type': 'message_enqueued',
    'version': 1,
    'created_at': '2017-09-11T17:20:51+00:00',
    'logged_at': '2017-09-11T17:21:51+00:00',
    'message_id': '7b65c566-6352-4440-b51c-c69f1e1fb888',
    'campaign_pk': '3ce70fde-c0de-402d-bd7c-985b459c3b13',
    'post_pk': 'e42d6cdc-4721-4f37-9386-08812dc98441',
    'contact_pk': 'f51e734a-e27d-4696-8340-5426308aba11',
    'mail_to': 'example@smaily.com',
}



message_delivered

Emitted when message has been delivered.


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

Field
Type

from_ip
IP-address
IP-address of the sending email server.
to_ip
IP-address
IP-address of the receiving email server.
status
String
Receiving email server's SMTP response.
status_smtp_reply
String
Receiving email server's raw SMTP reply string.
status_code
String
Normalized SMTP response. It's value should always be ok.


Example document:

{
    'event_id': 'f9e7f5df-3eb1-44e1-9fd7-d0914a0830ea',
    'type': 'message_delivered',
    'version': 1,
    'created_at': '2017-09-11T17:20:51+00:00',
    'logged_at': '2017-09-11T17:21:51+00:00',
    'message_id': '7b65c566-6352-4440-b51c-c69f1e1fb888',
    'campaign_pk': '3ce70fde-c0de-402d-bd7c-985b459c3b13',
    'post_pk': 'e42d6cdc-4721-4f37-9386-08812dc98441',
    'contact_pk': 'f51e734a-e27d-4696-8340-5426308aba11',
    'from_ip': '1.2.3.4',
    'to_ip': '5.6.7.8',
    'status': '2.0.0 (success)',
    'status_smtp_reply': '250 2.0.0 OK 1485961803 m131si21552321wmd.60 - gsmtp',
    'status_code': 'ok',
}



message_bounced

Emitted when message has bounced.


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

Field
Type

from_ip
IP-address
IP-address of the bounce origin.
status
String
Bounce SMTP status code.
status_smtp_reply
String
Raw SMTP reply string.
status_code
String
Normalized SMTP response. See message status classificators for details.
status_severity
String
Bounce severity. Has either the value of soft (temporary bounce) or hard (permanent bounce).


Example document:

{
    'event_id': 'f9e7f5df-3eb1-44e1-9fd7-d0914a0830ea',
    'type': 'message_bounced',
    'version': 1,
    'created_at': '2017-09-11T17:20:51+00:00',
    'logged_at': '2017-09-11T17:21:51+00:00',
    'message_id': '7b65c566-6352-4440-b51c-c69f1e1fb888',
    'campaign_pk': '3ce70fde-c0de-402d-bd7c-985b459c3b13',
    'post_pk': 'e42d6cdc-4721-4f37-9386-08812dc98441',
    'contact_pk': 'f51e734a-e27d-4696-8340-5426308aba11',
    'from_ip': '2.4.6.8',
    'status': '5.1.1 (bad destination mailbox address)',
    'status_smtp_reply': '550 5.1.1 <example@smaily.com>: Recipient address rejected: User unknown in virtual mailbox table',
    'status_code': 'bad-mailbox',
    'status_severity': 'hard',
}



message_global_bounced

Emitted when message's recipient is in global suppression list, and delivery to said contact is not allowed.


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

Field
Type

status_code
String
Normalized SMTP response. See message status classificators for details.


Example document:

{
    'event_id': 'f9e7f5df-3eb1-44e1-9fd7-d0914a0830ea',
    'type': 'message_global_bounced',
    'version': 1,
    'created_at': '2017-09-11T17:20:51+00:00',
    'logged_at': '2017-09-11T17:21:51+00:00',
    'message_id': '7b65c566-6352-4440-b51c-c69f1e1fb888',
    'campaign_pk': '3ce70fde-c0de-402d-bd7c-985b459c3b13',
    'post_pk': 'e42d6cdc-4721-4f37-9386-08812dc98441',
    'contact_pk': 'f51e734a-e27d-4696-8340-5426308aba11',
    'status_code': 'bad-mailbox',
}



message_reported

Emitted when message is reported as SPAM by recipient.


Example document:

{
    'event_id': 'f9e7f5df-3eb1-44e1-9fd7-d0914a0830ea',
    'type': 'message_reported',
    'version': 1,
    'created_at': '2017-09-11T17:20:51+00:00',
    'logged_at': '2017-09-11T17:21:51+00:00',
    'message_id': '7b65c566-6352-4440-b51c-c69f1e1fb888',
    'campaign_pk': '3ce70fde-c0de-402d-bd7c-985b459c3b13',
    'post_pk': 'e42d6cdc-4721-4f37-9386-08812dc98441',
    'contact_pk': 'f51e734a-e27d-4696-8340-5426308aba11',
}



message_forwarded

Emitted when message is forwarded by recipient using Send to Friend functionality.


Example document:

{
    'event_id': 'f9e7f5df-3eb1-44e1-9fd7-d0914a0830ea',
    'type': 'message_forwarded',
    'version': 1,
    'created_at': '2017-09-11T17:20:51+00:00',
    'logged_at': '2017-09-11T17:21:51+00:00',
    'message_id': '7b65c566-6352-4440-b51c-c69f1e1fb888',
    'campaign_pk': '3ce70fde-c0de-402d-bd7c-985b459c3b13',
    'post_pk': 'e42d6cdc-4721-4f37-9386-08812dc98441',
    'contact_pk': 'f51e734a-e27d-4696-8340-5426308aba11',
}