In this section:

Query Mail Events

Once a mail has been sent it typically generates one or more events like Bounce, Open, Click, Spam Complaint or Unsubscribe. The events are important to analyze how recipients interact with your mails and to keep your contact database up to date. Please note that even if an email has been sent there is no guarantee that it will actually be delivered to the recipient. If a mail cannot be delivered this usually results in a so-calledBounce. So if you want to know whether somebody got a certain email you need to query the bounce events as well as the sent events.

According to the description above, the following event types are collected and can be accessed through the provided endpoints:

  • Sent – A mail was forwarded by the system to a recipient.
  • Bounces – A mail could not be delivered.
  • Clicks – A tracked link in a mail was clicked.
  • Opens – A mail was opened.
  • Spam Complaints – A recipient reported your mails as spam.
  • Unsubscribes – A recipient unsubscribed from your mails.

The external_id Field

The external_id field can be useful to connect the mail event data to the contact data at your end. The field’s content is unique for each recipient on your side and will be delivered along with other fields when querying the mail events.

You can benefit from using the external_id field if the email address is not sufficient to uniquely identify a recipient. Example use cases include:

  • The same contact has multiple accounts in your environment.
  • The same contact registers for an account, unregisters and registers again with the same email address.

To use the external_id field, proceed as follows:

  • Add the external_id field to the Assigned Fields of the respective mail template.
  • When you append data to the respective mail stream you pass the external_id together with the other fields.

Querying Events

Each event type is available through its own resources. All resources work the same way and accept the same parameters (see below for more information).

It is good industry practice to download event data at regular intervals (e.g. every 2 hours).

Endpoint

GET https://api.emarsys.net/api/rtm/mail_events/<event_type>

Parameters

  • from –  An ISO8601 timestamp with time zone, specifying the start of the interval of interest (inclusive)
  • to – An ISO8601 timestamp with time zone, specifying the end of the interval of interest (exclusive)
  • email – An e-mail address to be used as a filter for mail events.
  • external_id – The external ID to be used as a filter for mail events.

Notes:

 

The time span between from and to parameter must be smaller than or equal to 24 hours, the to parameter must be at least 25 minutes in the past and the from parameter must not be more than 4 weeks in the past.

  • The parameters email and external_id
    • only have an effect on the event types sent and bounces,
    • are mutually exclusive and
    • are mandatory for the sent resource.

Response

The events will be delivered in text/csv format. The following columns will be present for all event types.

  • mail_stream_id – ID of the mail stream the mail was sent through.
  • recipient_id – ID of the recipient to whom the mail was sent (the same as returned when posting the recipients).
  • timestamp – The time of the event as a ISO8601 timestamp.
  • email – The recipient email address.
  • external_id – Additional ID which can be included in the recipient data for creating a relationship between the mail event data and the recipient data on your end.

Request Rate Limit

The number of requests to the event resources is limited to 1000 requests/hour. Once this limit has been reached all further requests to any event resource will be rejected with a 429 error (Too Many Requests).

Compression

It is good practice to use compression. If your system can handle gzip compression, you can include the HTTP header Accept-Encoding: gzip in the request.

The content of the response will be compressed using gzip and the HTTP header Content-Encoding: gzip will be present in the response. This will result in faster downloads and less bandwidth being used.

Querying Sent

The event type sent can be used to check for a given time frame if and when a mail was forwarded by the system to a specific recipient.

Notes:

  • It is mandatory to specify one of the mutually exclusive parameters email and external_id beside from and to in the request!
  • Querying sent events is only offered to support a fast lookup option for a specific recipient. It is not intended for querying all sent recipients for a specific time frame as this information already can be collected on user side (refer to Append to mail stream).

GET

/api/rtm/mail_events/sent?from=2016-07-12T00%3A00%3A00%2B0200&to=2016-07-12T23%3A00%3A00%2B0200&email=john.doe@example.com

Response Body (Example)

mail_stream_id,recipient_id,timestamp,email,external_id
Test_MX_V4,506801269562671104,2016-07-12 10:09:33.343+02,john.doe@example.com,
Test_MX_V4,290628492129730560,2016-07-12 10:14:11.675+02,john.doe@example.com,
AT_MV_V2,506801237568520192,2016-07-12 09:37:47.5+02,john.doe@example.com,
AT_MV_V2,218570862205337600,2016-07-12 09:38:34.732+02,john.doe@example.com,
AT_MV_V2,74455675136114688,2016-07-12 09:39:32.788+02,john.doe@example.com,
AT_MV_V2,506801241527943168,2016-07-12 09:41:41.992+02,john.doe@example.com,
AT_MV_V2,74455678726438912,2016-07-12 09:43:06.954+02,john.doe@example.com,

Querying Bounces

When querying bounces there will be one additional column in the response, called bounce_code. This column indicates which kind of bounce was encountered:

  • block for block bounce.
  • hard for hard bounce.
  • soft for soft bounce.
  • suppressed for sending suppression due to filtering.
  • invalid_address for mails not sent due to invalid email address.

Beside the mandatory parameters from and to it is allowed to use the optional parameters email or external_id for this event type.

GET

/api/rtm/mail_events/bounces?from=2014-03-24T13%3A00%3A00%2B0100&to=2014-03-24T16%3A30%3A00%2B0100

Response Body (Example)

mail_stream_id,recipient_id,timestamp,email,external_id,bounce_code
AT_Test1_20140312_GU,1000,2014-03-24T10:15:00+02,john.doe@example.com,4948335,block
AT_Test4_20140312_GU,1001,2014-03-24T10:25:00+02,jane.doe@example.com,1877213,suppressed

Querying Opens

GET

/api/rtm/mail_events/opens?from=2014-03-24T13%3A00%3A00%2B0100&to=2014-03-24T16%3A30%3A00%2B0100

Response Body (Example)

mail_stream_id,recipient_id,timestamp,email,external_id,recipient_user_agent,recipient_device,recipient_operating_system,recipient_ip
AT_Test1_20140312_GU,1000,2014-03-24T10:15:00+02,john.doe@example.com,4948335,Firefox 36.0,Personal computer,Linux (Ubuntu),192.168.24.2
AT_Test4_20140312_GU,1001,2014-03-24T10:25:00+02,jane.doe@example.com,1877213,Firefox 36.0,Personal computer,Linux (Ubuntu),192.168.24.2

Querying Clicks

This returns an additional url column which contains the target URL of the link clicked.

GET

/api/rtm/mail_events/clicks?from=2014-03-24T13%3A00%3A00%2B0100&to=2014-03-24T16%3A30%3A00%2B0100

Response Body (Example)

mail_stream_id,recipient_id,timestamp,email,external_id,url,recipient_user_agent,recipient_device,recipient_operating_system,recipient_ip
AT_Test1_20140312_GU,1000,2014-03-24T10:15:00+02,john.doe@example.com,4948335,http://example.com,Firefox 36.0,Personal computer,Linux (Ubuntu),192.168.24.2
AT_Test4_20140312_GU,1001,2014-03-24T10:25:00+02,jane.doe@example.com,1877213,http://example.com,Firefox 36.0,Personal computer,Linux (Ubuntu),192.168.24.2

Querying Unsubscribes

This returns an additional field_id column which contains the identifier of the unsubscribe field. This can be useful if more than one unsubscribe field is configured for this account (the default value is0).

GET

/api/rtm/mail_events/unsubscribes?from=2014-03-24T13%3A00%3A00%2B0100&to=2014-03-24T16%3A30%3A00%2B0100

Response Body (Example)

mail_stream_id,recipient_id,timestamp,email,external_id,field_id
AT_Test1_20140312_GU,1000,2014-03-24T10:15:00+02,john.doe@example.com,4948335,0
AT_Test4_20140312_GU,1001,2014-03-24T10:25:00+02,jane.doe@example.com,1877213,0

Errors

HTTP Code Reply Code Message Description
400 1001 One or more parameters are invalid or missing.  
400 4000 One or more specified parameters are invalid.  
429 7003 Too many requests for this account and resource within the last hour.  
503 – The system is overloaded for this resource.