Overview

Skill Level: Intermediate

Prerequisites

This interface allows exporting unique contact-level events and creates a compressed file that contains a single flat file with all metrics. You can request all (or a subset) of the Event Types.

Step-by-step

  1. Syntax of the request and response XML for RawRecipientDataExport

    The API gives the ability to specify:

    • One or more mailings
    • One or more Mailing/Report ID combinations (for Autoresponders)
    • A specific database (optional – include related queries)
    • A specific Group of Automated Messages
    • An Event Date Range
    • A Mailing Date Range

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

    Events, such as Automated Messages, can be filtered by Mailing type when exported within a date range. This API provides the ability to export of all events that are not yet exported. This allows exporting on a recurring basis without specifying date ranges. Watson Campaign Automation returns any event that is not previously exported by the user.

    RawRecipientDataExport includes only the events that are not exported by the user that is calling the API. Can use with a particular Mailing, Group of Automated Messages, or database and/or along with a date range. If you do not specify a date range, Watson Campaign Automation uses the last 30 days to filter the results.
     
    Note: As an alternative to the RawRecipientDataExport, consider using the Bulk Event Export (BEX) API, a feature where the Org Admin users of the organization can define specific export jobs for the events generated for or by the contacts of a specific database.
     
    Operation <RawRecipientDataExport>
    Elements

    MAILING_ID

    Optional ID of the mailing for which to export events. You can specify more than one mailing by surrounding each Mailing ID with <MAILING> parent element tags. For example, if you want to specify more than one mailing 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

    Optional

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

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

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

    CAMPAIGN_ID

    Optional

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

     

    LIST_ID

    Optional

    Used as an alternative to Mailing ID or Group of Automated Messages. When specified, the Watson Campaign Automation returns data for all mailings 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

    Optional

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

     

    ALL_NON_EXPORTED

    Optional Includes the events that are not exported by the user that calls the API. Can use with a particular Mailing, Group of Automated Messages, or database and/or along with a
    date range. If you do not specify a date range, the Watson Campaign Automation uses the last 30 days to filter the results.

    Note: When this element is used, Watson Campaign Automation will flag exported events for future exports. Exports that are 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

    Optional

    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

    Optional

    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 the Watson Campaign Automation is tracking the Organization’s mailings. 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

    Optional

    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 the Watson Campaign Automation is tracking the Organization’s mailings.

     

    SEND_DATE_END

    Optional

    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

    Optional Defines the formatting of the source file. Supported values are:

    • 0 – CSV file 1 – Pipe-separated file 2 – Tab-separated file

    If not specified, the Watson Campaign Automation uses the default format (CSV).

      RETURN_FROM_ADDRESS Optional Returns the From Address that is set for each mailing.

    Note: For Dynamic Content and Personalization, the following occurs:

    • If mailing contains Dynamic Content in the mail template, the values that are exported are the values for the From Name and/or From Address for the owner of the mail template (for example, the values populated in the mail template by default when it was created).
    • If the From Name and/or From Address is changed in the mail 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 mail 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 mail 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 mail template what is exported is the values for the From Name and/or From Address for the owner of the mail template (for example, the values populated in the mail template by default when it was created).
      RETURN_FROM_NAME Optional Returns the From Name that is set for each mailing.

    Note: For Dynamic Content and Personalization, the following occurs:

    • If mailing contains Dynamic Content in the mail template, the values that are exported are the values for the From Name and/or From Address for the owner of the mail template (for example, the values populated in the mail template by default when it was created).
    • If the From Name and/or From Address is changed in the mail 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 mail 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 mail 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 mail template what is exported is the values for the From Name and/or From Address for the owner of the mail template (for example, the values populated in the mail template by default when it was created).
      FILE_ENCODING Optional Defines the encoding of the exported file. Supported values are:

    • utf-8
    • iso-8859-1

    If not specified, the Watson Campaign Automation uses the Organization’s default encoding.

     

    EXPORT_FILE_NAME

    Optional 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

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

    MOVE_TO_FTP

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

    PRIVATE

    Optional

    Parameter to retrieve private mailings. If the API does not receive a Private or Shared designation, the Watson Campaign Automation returns both private and shared mailings.

     

    SHARED

    Optional

    Parameter to retrieve shared mailings.

     

    SENT_MAILINGS

    Optional

    Mailing Type parameter to retrieve sent mailings.

     

    SENDING

    Optional

    Mailing Type parameter to retrieve mailings during sending.

     

    OPTIN_CONFIRMATION

    Optional

    Mailing Type parameter to retrieve Opt-In Autoresponder mailings.

     

    PROFILE_CONFIRMATION

    Optional

    Mailing Type parameter to retrieve Edit Profile Autoresponder mailings.

     

    AUTOMATED

    Optional

    Mailing Type parameter to retrieve Custom Autoresponder mailings.

     

    CAMPAIGN_ACTIVE

    Optional

    Mailing Type parameter to retrieve active Groups of Automated Messages.

     

    CAMPAIGN_COMPLETED

    Optional

    Mailing Type parameter to retrieve completed Groups of Automated Messages.

     

    CAMPAIGN_CANCELLED

    Optional

    Mailing Type parameter to retrieve canceled Groups of Automated Messages.

     

    CAMPAIGN_SCRAPE_TEMPLATE

    Optional

    Mailing Type parameter to retrieve mailings that use content retrieval.

     

    INCLUDE_TEST_MAILINGS

    Optional

    Specify to include Test Mailings. If you do not provide this element, the Watson Campaign Automation does return any test mailings.

     

    ALL_EVENT_TYPES

    Optional

    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 Optional

    Specify to receive Sent events.

    Note: Suppressed contacts are not included. If a mailing is sending (for example, Throttle Mailings) and you start the ALL_NON_EXPORTED feature, the Watson Campaign Automation does not include Sent events until it sends to all contacts.
     

    SUPPRESSED

    Optional

    Specify to receive Suppressed events.

    Note: Suppressed contacts are not included. If a mailing is sending (for example, Throttle Mailings) and you start the ALL_NON_EXPORTED feature, the Watson Campaign Automation does not include Suppressed events until it sends to all contacts.
      OPENS Optional

    Specify to receive Open events.

      CLICKS Optional

    Specify to receive Clickthrough events.

     

    OPTINS

    Optional

    Specify to receive Opt In events.

     

    OPTOUTS

    Optional

    Specify to receive Opt Out events.

      FORWARDS Optional

    Specify to receive Forwarded events.

     

    ATTACHMENTS

    Optional

    Specify to receive Attachment events.

     

    CONVERSIONS

    Optional

    Specify to receive Conversion events.

     

    CLICKSTREAMS

    Optional

    Specify to receive Clickstream events.

     

    HARD_BOUNCES

    Optional

    Specify to receive Hard Bounce events.

     

    SOFT_BOUNCES

    Optional

    Specify to receive Soft Bounce events.

     

    REPLY_ABUSE

    Optional

    Use to receive Reply – Abuse events.

     

    REPLY_COA

    Optional

    Use to receive Reply – Change of Address events.

     

    REPLY_OTHER

    Optional

    Use to receive Reply – Other events.

     

    MAIL_BLOCKS

    Optional

    Use to receive Mail Block events.

     

    MAILING_RESTRICTIONS

    Optional

    Use to receive Mail Restricted events.

     

    INCLUDE_SEEDS

    Optional

    Specify to include Seed contacts.

    Note: If you delete a Seed contact from the Seed List, the Watson Campaign Automation does not export the associated events.
     

    INCLUDE_FORWARDS

    Optional

    Use to include Forwarded contacts.

     

    INCLUDE_INBOX_MONITORING

    Optional

    Use to include Inbox Monitoring contacts.

     

    CODED_TYPE_FIELDS

    Optional

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

     

    EXCLUDE_DELETED

    Optional

    Use to exclude events for contacts who were deleted/purged from their database.

    Note: 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

    Optional

    Used to retrieve only events that are taken by forwarded recipients.

     

    RETURN_MAILING_NAME

    Optional

    Specify to include Mailing Name in the generated file. If not specified, ‘false’ is assumed.

     

    RETURN_SUBJECT

    Optional

    Specify to include Mailing Subject in the generated file. If not specified, ‘false’ is assumed.

     

    RETURN_CRM_CAMPAIGN_ID

    Optional

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

     

    RETURN_PROGRAM_ID

    Optional

    Specify to include the Program ID that a Mailing was triggered from (if applicable).

    Optional Child Elements COLUMNS Optional XML Node used to request list columns to export for each
    contact.
      Child Element COLUMN
      NAME Child Element NAME Specifies the field name.
    Example
    <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>admin@yourorg.com</EMAIL>
          <ALL_EVENT_TYPES/>
          <INCLUDE_INBOX_MONITORING/>
          <COLUMNS>
            <COLUMN>
              <NAME>CustomerID</NAME>
            </COLUMN>
            <COLUMN>
              <NAME>Address</NAME>
            </COLUMN>
          </COLUMNS>
        </RawRecipientDataExport>
      </Body>
    </Envelope>
    

    Response <RESULT>
    Elements SUCCESS True if successful.
      MAILING XML nodes that define the user-created column name and
    value.
      ChildElement 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.
    Example
    <Envelope>
      <Body>
        <RESULT>
          <SUCCESS>TRUE</SUCCESS>
          <MAILING>
            <JOB_ID>72649</JOB_ID>
            <FILE_PATH>15167_20041213100410_track.zip</FILE_PATH>
          </MAILING>
        </RESULT>
      </Body>
    </Envelope>
    

    Example with optional FROM_ADDRESS parameter
    <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>
    

    Example with optional FROM_NAME parameter.
    <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>
    

    A single file export with the following columns that are populated for each event:

    Column Description

    Recipient ID

    The ID of the contact that is associated with the event.

    Recipient Type

    The type of contact to whom the Watson Campaign Automation sent the mailing. Valid values are:

    • Normal – 0
    • Forward – 1
    • Seed – 3
    • Inbox Monitoring – 4

    Mailing ID

    The ID of the Sent Mailing that is associated with the event.

    Report ID

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

    Campaign ID

    The ID of the Group of Automated Messages that are associated with the event.

    Email

    The contact’s email address.

    Event Type The type of contact event. Valid values 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.

    You can (optionally) populate the following columns based on the Event Type:

    Column

    Description

    Event Types

    Body Type

    The body type the contact received. Valid values are:

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

    Clickthrough, Open

    Content ID

    The user-specified identifier of the attachment.

    Attachments

    Click Name

    The user-specified name of the link or Clickstream.

    Clickthrough, Clickstream

    URL

    The hyperlink of a Clickthrough or Clickstream.

    Clickthrough, Clickstream

    Conversion Action

    The user-specified action of a conversion.

    Conversion

    Conversion Detail

    The user-specified description of a conversion.

    Conversion

    Conversion Amount

    The dollar amount of a conversion.

    Conversion

    Suppression Reason

    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

    Suppressed

    You can optionally populate the following columns by requesting them in the request (they are returned between the Suppression Reason and the requested database columns):

    Column

    Description

    Mailing Name

    The Mailing Name of the mailing that is 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 mailing that is associated with the event. This column is only present if RETURN_SUBJECT is specified in the request.

    CRM Campaign ID

    The CRM Campaign ID that is linked to the mailing associated with the event. This column is only present if RETURN_CRM_CAMPAIGN_ID is specified in the request.

    Note: This column populates only for mailings that are associated with a Campaign in a CRM system. Data Dictionary

    The following table contains the current API field data definitions for this API. These definitions are subject to change.

    Field Name Data Type Size (Characters)
    Recipient ID Numeric 18
    Recipient Type Text 5
    Mailing ID Numeric 38
    Report ID Numeric 18
    Campaign ID Numeric 18
    Email Text 255
    Event Type Text 3
    Event Timestamp Date Time 6
    Body Type Text 1
    Content ID Text 55
    Click Name Text 350
    URL Text 1000 (Clickstream URL)
    Conversion Action Text 128
    Conversion Detail Text 128
    Conversion Amount Numeric 22
    Suppression Reason Text 18
    Mailing Name Text 255
    Mailing Subject Text 255
    CRM Campaign ID Numeric 18
    ContactID Numeric 18

7 comments on"Export raw contact events"

  1. I’m looking for specific definitions of the event types, specifically the “unsuccessful” ones like suppressed, soft bounce, hard bounce, reply mail block, etc. Is this documented anywhere?

  2. How can I pull ONLY automated campaigns using xml? I want to be able to pull more than one campaign using xml

    • Hello Alex,
      Are you speaking about wanting to pull Programs that are currently running?

      Thank you

  3. Did you find a solution? to pull two or more campaigns?

  4. Santiago Moreau March 21, 2019

    Hi,

    is there a way to have a report where you have the hard_bounces + the soft_bounce with an event date higher than 5 days?

    regards,

    Santiago

Join The Discussion

Your email address will not be published. Required fields are marked *