Request email report

Email Report

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

Generating a report is an asynchronous operation. Once it's been requested you can check the status using the corresponding GET /emails/reports/{report_id} endpoint. When it's completed then that the response from that endpoint instructs you on how to retrieve the report file.

Report file

The following events are included in the report file:

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

The report 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 report 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 report 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 report files follows the type of the attribute. Read more about attribute types in this Help Center article.

Limits

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

The report file can include up to 75 attributes and 25 tags. Validated when requesting a report.

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

Maximum file size limit. If you request a report 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 report 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

Language
Authentication
Bearer
URL
Click Try It! to start a request and see the response here!