Export raw contact events - RawRecipientDataExport

Overview

Exports unique contact-level events and creates a compressed file that contains a single flat file with all metrics.
This API gives the ability to specify:

• One or more emails
• One or more email/Report ID combinations (for autoresponders)
• A specific database (optional – include related queries)
• A specific group of automated messages
• An event date range
• An email date range

📘

Note:

When private mailings (mailing not owned by the user calling the API) are explicitly specified or are determined based on a specified Database, Group of Automated Messages, or Date Range, then the events associated with that mailing are not included in the resulting file. No error will be returned, and all other mailing events will be included in the file.

👍

Consider the Bulk Event Export (BEX) API

As an alternative to RawRecipientDataExport, consider using the Bulk Export (BEX) API , a feature where org admin users of the organization can define specific export jobs for the events generated for or by the contacts of a specific database.

Elements

📘

All elements are considered optional

The following elements can be used in a variety of combinations to provide the results you desire. Determine what elements you need by reading their descriptions and compare to the examples below.

MAILING_ID - ID of the email to export events. You can get the Mailing ID from the Email campaigns view by hovering over the email name. The MAILING_ID retrieves data from a specific mailing. You can specify more than one email by surrounding each Mailing ID with parent element tags. For example, if you want to specify more than one email to extract data from use the following as a guide:

<MAILING>
  <MAILING_ID>5262609</MAILING_ID>
</MAILING>
<MAILING>
  <MAILING_ID>4667603</MAILING_ID>
</MAILING>

REPORT_ID - Used with a Group of Automated Messages to gather metrics for a certain instance of the email. You can specify more than one Mailing or Report ID by surrounding each pair with a element. For example, if you want to specify more than one email to extract data from use the following as a guide:

<MAILING>
  <REPORT_ID>502993</REPORT_ID>
</MAILING>
<MAILING>
  <REPORT_ID>98765</REPORT_ID>
</MAILING>

Note: Depending on the type of email, Report IDs can be assigned in a number of ways. For Autoresponders, a single Report ID is associated with every email for a day. For a recurring Automated Message, a single Report ID is associated with each occurrence of the email. For a standard email, a one-to-one relationship between a Report ID and Mailing ID exists.

CAMPAIGN_ID - ID for the Group of Automated Messages for which to export events. When specified, Acoustic Campaign returns data for all emails that are associated with the Automated Message. Do not use the group’s ID and Mailing ID at the same time.

LIST_ID - Used as an alternative to Mailing ID or Group of Automated Messages. When specified, Acoustic Campaign returns data for all emails that are associated with the database ID or Query ID. Do not use database ID, Mailing ID, or Group of Automated Messages at the same time.

INCLUDE_CHILDREN - If you provide a database ID, this element allows retrieving emails for queries and contact lists based on the specified database.

ALL_NON_EXPORTED - Includes the events not exported by the user that calls the API. Can use with a particular email, group of automated messages, or database and/or along with a
date range. If you do not specify a date range, Acoustic Campaign uses the last 30 days to filter the results.

📘

Note for ALL_NON_EXPORTED

When this element is used, Campaign flags exported events for future exports. Exports initiated without this element do not flag exported events. A single user cannot use this function with more than one set of event types. Use multiple user accounts when setting up multiple scheduled jobs that request different sets of event types with this function (for example, One job for OPENS and CLICKS and another job for OPTOUTS).

EVENT_DATE_START - Specifies the beginning boundary of activity for information to receive. If not specified, the start date of the event defaults to the start date of the mail send. If you do not specify Event Date Range or Send Date Range, the system defaults Event Date Range to the last 30 days.

EVENT_DATE_END - Specifies the ending boundary of activity for information to receive. If you do not specify Event Date Range, the Event Date End defaults to the Send Date End plus the number of days Acoustic Campaign is tracking the organization’s emails. If you do not specify Event Date Range or Send Date Range, the system defaults the Event Date Range to the last 30 days.

SEND_DATE_START - Specifies the beginning “Send” boundary for information to receive. If you do not specify Send Date Range, the Send Date Start defaults to Event Date Start minus the number of days Acoustic Campaign is tracking the organization’s emails.

SEND_DATE_END - Specifies the ending “Send” boundary for information to receive. If you do not specify Send Date Range, the Send Date End defaults to the Event Date End.

EXPORT_FORMAT - Defines the formatting of the source file. Supported values are: 0 (CSV file), 1 (Pipe-separated file), or 2 (Tab-separated file).
If not specified, Acoustic Campaign uses the default format (CSV).

RETURN_FROM_ADDRESS - Returns the From Address that is set for each email.

RETURN_FROM_NAME - Returns the From Name that is set for each email.

📘

Dynamic content and personalization with RETURN_FROM_ADDRESS and RETURN_FROM_NAME

If the email contains Dynamic Content in the email template, the values exported are the values for the From Name and/or From Address for the owner of the email template (for example, the values populated in the email template by default when it was created).

If the From Name and/or From Address is changed in the email template; the changed value is what is exported for the From Name and/or From Address.

If the From Name and/or From Address is changed in a program configuration for email template; the changed value is what is exported for the From Name and/or From Address.

If the From Name and/or From Address is changed in an Automated Message Group for email template; the changed value is what is exported for the From Name and/or From Address.

If the From Name and/or From Address is personalized in a email template what is exported is the values for the From Name and/or From Address for the owner of the email template (for example, the values populated in the email template by default when it was created).

FILE_ENCODING - Defines the encoding of the exported file. Supported values are:

• utf-8
• iso-8859-1
  If not specified, Acoustic Campaign uses the organization’s default encoding.

EXPORT_FILE_NAME - Specifies the output file name when an API request is submitted. This feature is used to avoid getting multiple files with the same name when jobs are submitted at or near same time. If specified, the value is used to replace ‘Raw Recipient Data Export’ in the file name. The date and time are appended to the file name.

EMAIL - If specified, the provided email address receives notification when the job is complete.

MOVE_TO_FTP - Use the MOVE_TO_FTP element to retrieve the output file programmatically. If specified, Acoustic Campaign moves the files to the download directory of the user’s FTP space. If you omit the MOVE_TO_FTP parameter, Acoustic Campaign places exported files in the Export Files area of Acoustic Campaign.

PRIVATE - Element to retrieve private emails. If the API does not receive a Private or Shared designation, Acoustic Campaign returns both private and shared emails.

SHARED - Element to retrieve shared emails.

SENT_MAILINGS - Email Type element to retrieve sent emails.

SENDING - Email Type element to retrieve emails during sending.

OPTIN_CONFIRMATION - Email Type element to retrieve Opt-In autoresponder emails.

PROFILE_CONFIRMATION - Email Type element to retrieve Edit Profile autoresponder emails.

AUTOMATED - Email Type element to retrieve custom autoresponder emails.

CAMPAIGN_ACTIVE - Email Type element to retrieve active Groups of Automated Messages.

CAMPAIGN_COMPLETED - Email Type element to retrieve completed Groups of Automated Messages.

CAMPAIGN_CANCELLED - Email Type element to retrieve canceled Groups of Automated Messages.

CAMPAIGN_SCRAPE_TEMPLATE - Email Type element to retrieve emails that use content retrieval.

INCLUDE_TEST_MAILINGS - Specify to include test emails. If you do not provide this element, Acoustic Campaign does return any test emails.

ALL_EVENT_TYPES - Specify to receive all events regardless of event type. If ALL_EVENT_TYPES is used, do not specify any of the individual metrics parameters.

SENT - Specify to receive Sent events.
Note: Suppressed contacts are not included. If an email is sending (for example, Throttle emails) and you start the ALL_NON_EXPORTED feature, Acoustic Campaign does not include sent events until it sends to all contacts.

SUPPRESSED - Specify to receive Suppressed events. Suppressed contacts are not included. If an email is sending (for example, Throttle emails) and you start the ALL_NON_EXPORTED feature, the Acoustic Campaign does not include Suppressed events until it sends to all contacts.

OPENS- Specify to receive Open events.

CLICKS - Specify to receive Clickthrough events.

OPTINS - Specify to receive Opt In events.

OPTOUTS - Specify to receive Opt Out events.

FORWARDS - Specify to receive Forwarded events.

ATTACHMENTS - Specify to receive Attachment events.

CONVERSIONS - Specify to receive Conversion events.

CLICKSTREAMS - Specify to receive Clickstream events.

HARD_BOUNCES - Specify to receive Hard Bounce events.

SOFT_BOUNCES - Specify to receive Soft Bounce events.

REPLY_ABUSE - Use to receive Reply–Abuse events.

REPLY_COA - Use to receive Reply–Change of Address events.

REPLY_OTHER - Use to receive Reply–Other events.

MAIL_BLOCKS - Use to receive email block events.

MAILING_RESTRICTIONS - Use to receive email restricted events.

INCLUDE_SEEDS - Specify to include seed contacts. If you delete a Seed contact from the Seed List, Acoustic Campaign does not export the associated events.

INCLUDE_FORWARDS - Use to include forwarded contacts.

CODED_TYPE_FIELDS - Use to return numeric values rather than strings in the following fields: Contact Type, Recipient Type, Event Type, Body Type, and Suppression Reason.

EXCLUDE_DELETED - Use to exclude events for contacts who were deleted/purged from their database. Inclusion of this element can greatly decrease the time to generate the metrics file and is useful whenever metrics for deleted contacts are not required.

FORWARDS_ONLY - Used to retrieve only events taken by forwarded recipients.

RETURN_MAILING_NAME - Specify to include email name in the generated file. If not specified, false is assumed.

RETURN_SUBJECT - Specify to include the email subject in the generated file. If not specified, false is assumed.

RETURN_CRM_CAMPAIGN_ID - Specify to include the CRM Campaign ID (when populated) in the generated file. If not specified, false is assumed.

RETURN_PROGRAM_ID - Specify to include the Program ID that an email was triggered from (if applicable).

COLUMNS - XML node used to request list columns to export for each contact. Contains the child element COLUMN and its child NAME.
COLUMN - XML node containing NAME as a child.
NAME - Specifies the field name.

<Envelope>
  <Body>
    <RawRecipientDataExport>
      <EVENT_DATE_START>12/01/2011 00:00:00</EVENT_DATE_START>
      <EVENT_DATE_END>12/02/2011 23:59:00</EVENT_DATE_END>
      <MOVE_TO_FTP/>
      <EXPORT_FORMAT>0</EXPORT_FORMAT>
      <EMAIL>[email protected]</EMAIL>
      <ALL_EVENT_TYPES/>
      <COLUMNS>
        <COLUMN>
          <NAME>CustomerID</NAME>
        </COLUMN>
        <COLUMN>
          <NAME>Address</NAME>
        </COLUMN>
      </COLUMNS>
    </RawRecipientDataExport>
  </Body>
</Envelope>

<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>TRUE</SUCCESS>
      <MAILING>
        <JOB_ID>72649</JOB_ID>
        <FILE_PATH>15167_20041213100410_track.zip</FILE_PATH>
      </MAILING>
    </RESULT>
  </Body>
</Envelope>

<Envelope>
  <Body>
    <RawRecipientDataExport>
      <EVENT_DATE_START>08/01/2016 00:00:00</EVENT_DATE_START>
      <EVENT_DATE_END>03/08/2017 23:59:00</EVENT_DATE_END>
      <SEND_DATE_START>08/01/2016 00:00:00</SEND_DATE_START>
      <SEND_DATE_END>03/08/2017 23:59:00</SEND_DATE_END>
      <EXPORT_FORMAT>0</EXPORT_FORMAT>
      <RETURN_FROM_ADDRESS/>
      <ALL_EVENT_TYPES/>
    </RawRecipientDataExport>
  </Body>
</Envelope>

<Envelope>
  <Body>
    <RawRecipientDataExport>
      <EVENT_DATE_START>08/01/2016 00:00:00</EVENT_DATE_START>
      <EVENT_DATE_END>03/08/2017 23:59:00</EVENT_DATE_END>
      <SEND_DATE_START>08/01/2016 00:00:00</SEND_DATE_START>
      <SEND_DATE_END>03/08/2017 23:59:00</SEND_DATE_END>
      <EXPORT_FORMAT>0</EXPORT_FORMAT>
      <RETURN_FROM_NAME/>
      <ALL_EVENT_TYPES/>
    </RawRecipientDataExport>
  </Body>
</Envelope>

Elements (Results)

SUCCESS - True if successful; False if not.

MAILING - XML nodes that define the user-created column name and value. Contains JOB_ID and FILE_PATH as child elements.
JOB_ID - Specifies resulting Background Job ID for the export. You can use this value with the GET_JOB_STATUS and/or DELETE_JOB_APIs.
FILE_PATH - Returns the file name of the export file.

A single file export with the following columns is populated for each event

Standard return

Recipient ID - The ID of the contact associated with the event.

Recipient Type -The type of contact to whom the Acoustic Campaign sent the email. If CODED_FIELD_TYPES is set to true, the Recipient Type is a numeric field with single-digit values. If the CODED_FIELD_TYPES is set to false, then it is a string field with a max of 16 characters.
Valid values for the numeric field are:

• Normal – 0
• Forward – 1
• Seed – 3

Mailing ID - The ID of the Sent email associated with the event.

Report ID - Depending on the type of email, Report IDs can be assigned in a number of ways. For event-driven autoresponders, a single Report ID is associated with every email for a day. For a recurring automated message, a single Report ID is associated with each occurrence of the email. For a standard email, a one-to-one relationship between a Report ID and Mailing ID exists.

Campaign ID - The ID of the group of Automated Messages associated with the event.

Email - The contact’s email address.

Event Type - The type of contact event. If CODED_FIELD_TYPES is set to true, the Event Type is a numeric field with double-digit values. If the CODED_FIELD_TYPES is set to false, it is a string field with a max of 22 characters for Reply Mail Restriction.
Valid values for the numeric field are:

• Open – 0
• Click Through – 1
• Clickstream – 2
• Conversion – 3
• Attachment – 4
• Media – 5
• Forward – 6
• Opt In – 7
• Opt Out – 8
• Reply Abuse – 10
• Reply Change Address – 11
• Reply Mail Block – 12
• Reply Mail Restriction – 13
• Reply Other – 14
• Suppressed – 15
• Sent – 16
• Soft Bounce – 98
• Hard Bounce – 99

Event Timestamp - The date and time of the event in the API user’s time zone. Event Timestamp is 19 characters (MM/dd/yyyy HH:mm:ss).

Optional columns populated by the Event Type

Body Type - (Clickthrough, Open) The body type the contact received. If CODED_FIELD_TYPES is set to true, the Body Type is a numeric field with single-digit values. If the CODED_FIELD_TYPES is set to false, it is a string field with a max of 4 characters (can be WEB, HTML, TEXT, or an empty string).
Valid values for the numeric field are:

• HTML – 0
• TEXT – 2
• WEB – 3 (Click-to-View)

Content ID - (Attachments) The user-specified identifier of the attachment.

Click Name - (Clickthrough, Clickstream) The user-specified name of the link or Clickstream.

URL - (Clickthrough, Clickstream) The hyperlink of a Clickthrough or Clickstream.

Conversion Action - (Conversion) The user-specified action of a conversion.

Conversion Detail - (Conversion) The user-specified description of a conversion.

Conversion Amount - (Conversion) The dollar amount of a conversion.

Suppression Reason - (Suppressed) The reason a contact was suppressed. Valid values are:

• Invalid System email Domain – 1
• Invalid System Email Local – 2
• Global Suppression List – 3
• Organization Suppression List – 4
• Invalid Organization Email Domain – 5
• Invalid Organization Email Local – 6
• Frequency Control – 7
• List Level Suppression – 8
• Query Level Suppression – 9
• Mailing Level Suppression – 10
• Duplicate Email in Nonkey List – 11
• IP Warming – 12

Optional columns populated by requesting them in the request (they return between the Suppression Reason and the requested database columns)

Mailing Name - The email name of the email associated with the event. This column is only present if RETURN_MAILING_NAME is specified in the request.

Mailing Subject - The Subject Line of the email associated with the event. This column is only present if RETURN_SUBJECT is specified in the request.

CRM Campaign ID - The CRM Campaign ID linked to the email associated with the event. This column is only present if RETURN_CRM_CAMPAIGN_ID is specified in the request and populates only for emails associated with a Campaign in a CRM system Data Dictionary

The current API field data definitions for RawRecipientDataExport

These definitions are subject to change