Message Events

The resources below help you you extract details about specific delivery and engagement events - opens, clicks, email bounces, etc.

get

Get a list of all bounce events

get

Get details for a specific bounce event

get

Get a list of all click events

get

get

Get a list of all open events

get

Retrieve open event details for a specific message

get

/bouncestatistics

Retrieve a list of all bounce events and details about them - message, contact and campaign IDs, timestamp etc.

Note: If no query parameters are used, will return events with FromTS equal to the current day at 00:00 UTC.

Full API path

Query string parameters

CampaignID

integer

Retrieves only bounce events linked to the specified campaign ID.

ContactsList

integer

Retrieves only bounce events linked to contacts from this contact list ID.

EventFromTs

string

Retrieves information only about bounce events that happened after the specified timestamp (BouncedAt >= EventFromTs). Can be used only if the CampaignID query parameter is specified as well.

EventToTs

string

Retrieves information only about bounce events that happened before the specified timestamp (BouncedAt <= EventFromTs). Can be used only if the CampaignID query parameter is specified as well.

FromTS

string

Retrieves information only about bounce events linked to campaigns sent after the specified timestamp.

Period

string

Retrieves information only about bounce events registered between the start of the selected period and the current timestamp.

Possible values:

  • Day - since the start of the current day
  • Week - since the start of the current week
  • Month - since the start of the current month
  • Year - since the start of the current year

ToTS

string

Retrieves information only about bounce events linked to campaigns sent before the specified timestamp.

Limit

integer

Limit the response to a select number of returned objects.

Default value: 10. Maximum value: 1000

Offset

integer

Retrieve a list of objects starting from a certain offset. Combine this query parameter with Limit to retrieve a specific section of the list of objects.

Default value: 0

countOnly

boolean

Set the value of this query parameter to 1 to retrieve the overall number of objects returned by this request for your API Key. No list of results will be returned - the objects will simply be counted.

Default value: 0

Note: When you send a request without the countOnly query parameter, Count and Total will only return the number of extracted elements and not the overall number.

Sort

string

Specify a property name for this query parameter to sort the objects in Data. By default the sorting is ascending. When a property name is postfixed with DESC (i.e. property_name DESC), the sort order will be descending.

Note: Both the Sort query parameter and the option to select a descending order are not available for every property.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Indicates the number of objects in the Data array.

Data

array

A JSON array containing a list of objects returned by this endpoint.

BouncedAt

string

Timestamp indicating when the bounce event occurred.

CampaignID

integer

Unique numeric ID of the campaign this bounce event is linked to.

ContactID

integer

Unique numeric ID of the contact this bounce event is linked to.

ID

integer

Unique numeric ID of the bounced message.

IsBlocked

boolean

Indicates whether the contact was blocked as a result of this bounce or not.

IsStatePermanent

boolean

Indicates whether this is a permanent (hard) bounce or not.

StateID

integer

State of the message after the bounce event:

  • 1 = user unknown (recipient)
  • 2 = mailbox inactive (recipient)
  • 3 = quota exceeded (recipient)
  • 4 = invalid domain (domain)
  • 5 = no mail host (domain)
  • 6 = relay/access denied (domain)
  • 7 = sender blocked (spam)
  • 8 = content blocked (spam)
  • 9 = policy issue (spam)
  • 10 = system issue (system)
  • 11 = protocol issue (system)
  • 12 = connection issue (system)
  • 13 = greylisted (domain)
  • 14 = preblocked (Mailjet)
  • 15 = duplicate in campaign (Mailjet)
  • 16 = spam preblocked (Mailjet)
  • 17 = bad or empty template (content)
  • 18 = error in template language (content)
  • 19 = typofix (domain)
  • 20 = blacklisted (recipient)
  • 21 = spam reporter (recipient)

Total

integer

Indicates the number of objects in the Data array.

get

/bouncestatistics/{message_ID}

Retrieve information about a specific bounce event.

Full API path

Path parameters

message_ID

integer, required

Unique numeric ID of the bounced message you want to retrieve information about.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Indicates the number of objects in the Data array.

Data

array

A JSON array containing a list of objects returned by this endpoint.

BouncedAt

string

Timestamp indicating when the bounce event occurred.

CampaignID

integer

Unique numeric ID of the campaign this bounce event is linked to.

ContactID

integer

Unique numeric ID of the contact this bounce event is linked to.

ID

integer

Unique numeric ID of the bounced message.

IsBlocked

boolean

Indicates whether the contact was blocked as a result of this bounce or not.

IsStatePermanent

boolean

Indicates whether this is a permanent (hard) bounce or not.

StateID

integer

State of the message after the bounce event:

  • 1 = user unknown (recipient)
  • 2 = mailbox inactive (recipient)
  • 3 = quota exceeded (recipient)
  • 4 = invalid domain (domain)
  • 5 = no mail host (domain)
  • 6 = relay/access denied (domain)
  • 7 = sender blocked (spam)
  • 8 = content blocked (spam)
  • 9 = policy issue (spam)
  • 10 = system issue (system)
  • 11 = protocol issue (system)
  • 12 = connection issue (system)
  • 13 = greylisted (domain)
  • 14 = preblocked (Mailjet)
  • 15 = duplicate in campaign (Mailjet)
  • 16 = spam preblocked (Mailjet)
  • 17 = bad or empty template (content)
  • 18 = error in template language (content)
  • 19 = typofix (domain)
  • 20 = blacklisted (recipient)
  • 21 = spam reporter (recipient)

Total

integer

Indicates the number of objects in the Data array.

get

/clickstatistics

Retrieve a list of all click events and details about them - message and contact IDs, timestamp, URL and click delay.

Note: If no query parameters are used, will return events with FromTS equal to the current day at 00:00 UTC.

Full API path

Query string parameters

CampaignID

integer

Retrieves only click events linked to the specified campaign ID.

ContactsList

integer

Retrieves only click events linked to contacts from this contact list ID.

CustomCampaign

string

Retrieves only click event details for the campaign with the specified custom value.

EventFromTs

string

Retrieves information only about click events that happened after the specified timestamp (ClickedAt >= EventFromTs). Can be used only if CampaignID query parameter is specified as well.

EventToTs

string

Retrieves information only about click events that happened before the specified timestamp (ClickedAt <= EventFromTs). Can be used only if CampaignID query parameter is specified as well.

FromTS

string

Retrieves information only about click events linked to campaigns sent after the specified timestamp.

From

string

Retrieves click event details only for the campaigns, which used the specified sender email address.

FromDomain

string

Retrieves click event details only for the campaigns, which used the specified sender email domain.

FromID

integer

Retrieves click event details only for the campaign, which used the specified sender ID.

FromType

integer

Retrieves click event details only for messages of the specified type:

  • 1 - Transactional
  • 2 - Marketing
  • 3 - Unknown

IsDeleted

boolean

When true, only click event details for deleted campaigns will be returned. When false, deleted campaigns will be excluded from the response.

IsNewsletterTool

boolean

When true, will return only click event details for campaigns created by the Newsletter tool (legacy template builder). When false, newsletter campaigns will be excluded.

MessageID

integer

Retrieves only click events linked to this message ID.

MessageStatus

integer

Retrieves only click events linked to messages with the specified status:

  • 0 (Processed)
  • 1 (Queued)
  • 2 (Sent)
  • 3 (Opened)
  • 4 (Clicked)
  • 5 (Bounce)
  • 6 (Spam)
  • 7 (Unsub)
  • 8 (Blocked)
  • 9 (SoftBounce)
  • 10 (HardBounce)
  • 11 (Deferred)

Period

string

Retrieves only information about click events registered between the start of the selected period and the current timestamp.

  • Day - since the start of the current day
  • Week - since the start of the current week
  • Month - since the start of the current month
  • Year - since the start of the current year

ToTS

string

Retrieves only information about click events linked to campaigns sent before the specified timestamp.

Limit

integer

Limit the response to a select number of returned objects.

Default value: 10. Maximum value: 1000

Offset

integer

Retrieve a list of objects starting from a certain offset. Combine this query parameter with Limit to retrieve a specific section of the list of objects.

Default value: 0

countOnly

boolean

Set the value of this query parameter to 1 to retrieve the overall number of objects returned by this request for your API Key. No list of results will be returned - the objects will simply be counted.

Default value: 0

Note: When you send a request without the countOnly query parameter, Count and Total will only return the number of extracted elements and not the overall number.

Sort

string

Specify a property name for this query parameter to sort the objects in Data. By default the sorting is ascending. When a property name is postfixed with DESC (i.e. property_name DESC), the sort order will be descending.

Note: Both the Sort query parameter and the option to select a descending order are not available for every property.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Indicates the number of objects in the Data array.

Data

array

A JSON array containing a list of objects returned by this endpoint.

ClickedAt

string

Timestamp indicating when the click event occurred.

ClickedDelay

integer

Delay (in seconds) between the message being opened and the URL link being clicked.

ContactID

integer

Unique numeric ID of the contact this click event is linked to.

ID

integer

Unique numeric ID for this click event.

MessageID

integer

Unique numeric ID of the message this click event is linked to.

Url

string

The URL that generated this click event.

UserAgentID

integer

Unique numeric ID for the user agent (browser) used for this click event.

Total

integer

Indicates the number of objects in the Data array.

get

/clickstatistics/{ID}

Click statistics for messages.

Full API path

Path parameters

ID

integer, required

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Indicates the number of objects in the Data array.

Data

array

A JSON array containing a list of objects returned by this endpoint.

ClickedAt

string

Timestamp indicating when the click event occurred.

ClickedDelay

integer

Delay (in seconds) between the message being opened and the URL link being clicked.

ContactID

integer

Unique numeric ID of the contact this click event is linked to.

ID

integer

Unique numeric ID for this click event.

MessageID

integer

Unique numeric ID of the message this click event is linked to.

Url

string

The URL that generated this click event.

UserAgentID

integer

Unique numeric ID for the user agent (browser) used for this click event.

Total

integer

Indicates the number of objects in the Data array.

get

/openinformation

Retrieve a list of all open events and details about them - message, campaign and contact IDs, timestamp etc.

Note: If no query parameters are used, will return events with FromTS equal to the current day at 00:00 UTC.

Full API path

Query string parameters

CampaignID

integer

Retrieves only open events linked to the specified campaign ID.

ContactsList

integer

Retrieves only open events linked to contacts from this contact list ID.

CustomCampaign

string

Retrieves only open event details for the campaign with the specified custom value.

EventFromTs

string

Retrieves information only about open events that happened after the specified timestamp (OpenedAt >= EventFromTs). Can be used only if the CampaignID query parameter is specified as well.

EventToTs

string

Retrieves information only about open events that happened before the specified timestamp (OpenedAt <= EventFromTs). Can be used only if the CampaignID query parameter is specified as well.

FromTS

string

Retrieves information only about open events linked to campaigns sent after the specified timestamp.

Note: If no query parameters are used, FromTS defaults to the current day at 00:00 UTC.

From

string

Retrieves only open event details for the campaigns, which used the specified sender email address.

FromDomain

string

Retrieves only open event details for the campaigns, which used the specified sender email domain.

FromID

integer

Retrieves only open event details for the campaign, which used the specified sender ID.

FromType

integer

Retrieves only open event details for the messages of the specified type:

  • 1 - Transactional
  • 2 - Marketing
  • 3 - Unknown

IsDeleted

boolean

When true, only open event details for deleted campaigns will be returned. When false, deleted campaigns will be excluded from the response.

MessageStatus

integer

Retrieves only open events linked to messages with the specified status:

  • 0 (Processed)
  • 1 (Queued)
  • 2 (Sent)
  • 3 (Opened)
  • 4 (Clicked)
  • 5 (Bounce)
  • 6 (Spam)
  • 7 (Unsub)
  • 8 (Blocked)
  • 9 (SoftBounce)
  • 10 (HardBounce)
  • 11 (Deferred)

Period

string

Retrieves information only about open events registered between the start of the selected period and the current timestamp.

  • Day - since the start of the current day
  • Week - since the start of the current week
  • Month - since the start of the current month
  • Year - since the start of the current year

ToTS

string

Retrieves information only about open events linked to campaigns sent before the specified timestamp.

Limit

integer

Limit the response to a select number of returned objects.

Default value: 10. Maximum value: 1000

Offset

integer

Retrieve a list of objects starting from a certain offset. Combine this query parameter with Limit to retrieve a specific section of the list of objects.

Default value: 0

countOnly

boolean

Set the value of this query parameter to 1 to retrieve the overall number of objects returned by this request for your API Key. No list of results will be returned - the objects will simply be counted.

Default value: 0

Note: When you send a request without the countOnly query parameter, Count and Total will only return the number of extracted elements and not the overall number.

Sort

string

Specify a property name for this query parameter to sort the objects in Data. By default the sorting is ascending. When a property name is postfixed with DESC (i.e. property_name DESC), the sort order will be descending.

Note: Both the Sort query parameter and the option to select a descending order are not available for every property.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Indicates the number of objects in the Data array.

Data

array

A JSON array containing a list of objects returned by this endpoint.

ArrivedAt

string

Timestamp indicating when the message arrived in the recipient's mailbox.

CampaignID

integer

Unique numeric ID of the campaign this open event is linked to.

ContactID

integer

Unique numeric ID of the contact this open event is linked to.

ID

integer

Unique numeric ID for this open event. Not returned by the API.

MessageID

integer

Unique numeric ID of the message this open event is linked to.

OpenedAt

string

Timestamp indicating when the message was opened by the reader for the first time.

UserAgentFull

string

Original User Agent String used to view this message.

UserAgentID

integer

Unique numeric ID for the user agent (browser) used for this click event.

Total

integer

Indicates the number of objects in the Data array.

get

/openinformation/{message_ID}

Retrieve open event details for a specific message.

Full API path

Path parameters

message_ID

integer, required

Unique numeric ID of the message you want to retrieve the open event information about.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Indicates the number of objects in the Data array.

Data

array

A JSON array containing a list of objects returned by this endpoint.

ArrivedAt

string

Timestamp indicating when the message arrived in the recipient's mailbox.

CampaignID

integer

Unique numeric ID of the campaign this open event is linked to.

ContactID

integer

Unique numeric ID of the contact this open event is linked to.

ID

integer

Unique numeric ID for this open event. Not returned by the API.

MessageID

integer

Unique numeric ID of the message this open event is linked to.

OpenedAt

string

Timestamp indicating when the message was opened by the reader for the first time.

UserAgentFull

string

Original User Agent String used to view this message.

UserAgentID

integer

Unique numeric ID for the user agent (browser) used for this click event.

Total

integer

Indicates the number of objects in the Data array.