Request email event export

Email event export

Request an export of email events decorated with selected attributes and tags since the specific start_at date, optionally to a specific end_at date.
You can also target a specific segment via the segment_filter property.

Generating an export is an asynchronous operation. Once it's been requested you can check the status and obtain the download link using the corresponding Get email event export status endpoint.

Export file

The following events are included in the export file:

• Sent
• Delivered
• Bounced
• Open
• Clicked
• Unsubscribed
• Reported spam

The export file is a GZIP compressed CSV file containing the following default columns:

• activity_id

  ID of the main activity. Activities can have sub-activities in case of split testing.

• split_id

  Activity ID of this event's sub-activity. Same as activity_id for non-split sendings and the winning partition in split tests.

• activity_name

  Name given to the activity

• split_activity_name

  Name of the split group

• sender

  Email sender name

• subject

  Email subject

• address

  Primary email address attribute of the targeted profile (from the same data section as the event)

• variation

  Split test recipient group. Empty for non-split sendings.

• type

  Event type

  • SENT
  • DELIVERED
  • OPENED
  • CLICKED
  • BOUNCED
  • UNSUBSCRIBED
  • ABUSE

• correlation_id

  ID for the event assigned by the event source (Email Tool). The same correlation_id value may be repeated if the event has been sent multiple times due to a retry logic.

• event_time

  Time of the event in milliseconds since Unix epoch reported by the event source. This feature was introduced at the beginning of 2020 so events prior to that may have event_time equal to 0. The value of 0 is also possible when the event source did not specify the event time. The dates in 1970 are possible when the event source specified the event time as 0 since they're interpreted as Unix epoch.

• server_time

  Time in milliseconds since Unix epoch when the event was received by One

• device

  Only for CLICKED and OPENED events. Values may be extended with new values and with additional data as suffix.

  • TABLET
  • MOBILE
  • DESKTOP
  • SMART_TV
  • UNKNOWN

• location

  Only for CLICKED and OPENED events. ISO 3166-1 alpha-2. May be extended with new data as suffix.

• link_id

  Only for CLICKED events. ID of the link.

• link_url

  Only for CLICKED events. URL of the link target.

• link_title

  Only for CLICKED events. Title given to the link in the email template.

• bounce_code

  Only for BOUNCED events. Detailed bounce reason.

  • 1000-1999 Rejected by recipient's server
  • 2000-2999 Invalid address (permanent)
    • 2001 Email address does not exist
    • 2002 Domain of address does not exist
    • 2004 Closed email account
  • 3000-3999 Address is temporarily unavailable
    • 3001 Mailbox is full
    • 3002 Recipient server is too busy
    • 3003 Email account is inactive
  • 4000-4999 Technical delivery problem
    • 4003 Network error
    • 4007 SPF authentication error
    • 4008 DMARC authentication error
    • 4009 DKIM authentication error
  • 5000-5999 Informational (out of office, auto reply etc.)
  • 9999 Unknown failure

• unsubscribe_topic

  Only for UNSUBSCRIBED events. Discriminator of the unsubscribed topic.

• abuse_section

  Only for ABUSE events. Discriminator of the abuse.

On top of the default columns the export file contains the fields requested in additional_attribute_mappings property for attributes and additional_tag_mappings property for tags. These have the headers following this pattern: gender (version_id: 491874). When a field is a tag, then the fact of it being set is denoted by the constant TAG in the export file.

In its requests and responses, APSIS One API supports date and time formatted as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.

Date format in the export files follows the type of the attribute. Read more about attribute types in this Help Center article.

Limits

Maximum export time window for events is three months. Validated when requesting a export.

The export file can contain up to 500 attributes and tags in total. Validated when requesting a export.

Pending export count limit. If reached, HTTP 429 Too Many Requests is returned.

Maximum file size limit. If you request a export with very large data set, i.e. many attributes or large time window that results in many events, you may receive a status of error when calling GET /emails/reports/{report_id}. You can then retry the export request aiming at a smaller data subset.

If there are over 25 sections on the account then HTTP 413 Request Entity Too Large may be returned

About events

Events are created in response to actions performed on activities.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.

Email activities can be fetched using the following endpoints:

• recent activities: GET /emails/sections/{section_discriminator}/activities
• specific activity: GET /emails/section/{section_discriminator}/activities/{activity_id}

More information

Video guides