Overview

Skill Level: Any

Prerequisites

This interface allows exporting unique contact‚Äźlevel events and creates a .zip file containing a single flat file with all metrics. You can request all (or a subset) of the Event Types. The API provides the ability to specify one of the following:

  • 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 calling the API‚ÄĒare explicitly specified or are determined based on a specified Database, Group of Automated Messages, or Date Range, the events associated with that mailing will not be included in the resulting file. No error will be returned and all other mailing events will be included in the file.

When exporting events within a date range, you can filter them by Mailing Type (for example, Automated Messages). This API provides the ability to export all events not yet exported. This allows exporting on a recurring basis without specifying date ranges. Watson Campaign Automation returns any event not previously exported by the user.

Step-by-step

  1. Syntax of the request and response SOAP for RawRecipientDataExport

    Operation  <RawRecipientDataExport>       
    Elements  MAILING_ID  Optional  ID of the mailing for which to export events. You can specify more than one mailing by surrounding Mailing IDs with <MAILING> elements.   
      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.

    Note: Depending on the type of mailing, you can assign Report IDs 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, there is a one‚Äźto‚Äźone relationship¬†between a Report ID and Mailing ID.

     
      CAMPAIGN_ID  Optional  ID for the Group of Automated Messages for which to export events.
    When specified, Watson Campaign Automation will return data for all mailings 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, Watson Campaign Automation will return data for all mailings 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_QUERIES  Optional  If you provide a Database ID, this element will allow retrieving mailings
    for queries based on the specified database.
     
      ALL_NON_EXPORTED  Optional 

    Only includes the events not exported by the user calling the API. Can
    use with a particular Mailing, Group of Automated Messages, or
    Database and/or in conjunction with a date range. If you do not specify
    a date range, Watson Campaign Automation will use 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 initiated without this element will not flag exported events. A single user should not use this function with more than one set of event types. Use multiple user accounts if setting up
    multiple scheduled jobs that request different sets of event types with
    this function (e.g. One job for OPENS and CLICKS; another job for
    OPTOUTS). 

     
      EVENT_DATE_START  Optional  Specifies the beginning boundary of activity for information to receive.
    If not specified, the Event Date Start will default to the Send Date Start. If you do not specify Event Date Range or Send Date Range, the system will default 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 will default to the Send Date End plus the number of days Watson Campaign Automation is tracking the Organization’s mailings. If you do not specify Event Date Range or
    Send Date Range, the system will default 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 will default to Event Date Start minus the number of days 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 will default to the Event Date End.
     
    Elements  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 you do not specify, Watson Campaign Automation will use the default format (CSV). 

     
      FILE_ENCODING  Optional

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

    utf‚Äź8
    iso‚Äź8859‚Äź1

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

     
      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, Watson Campaign Automation moves the files to the download directory of the user’s FTP space.

    If you omit the MOVE_TO_FTP parameter, Watson Campaign Automation will place exported
    files in the Export Files area of Watson Campaign Automation. 

     
      PRIVATE  Optional  Parameter to retrieve private mailings. If the API does not receive a Private or Shared designation, Watson Campaign Automation will return 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 in the process of 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,
    Watson Campaign Automation will not 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 in the
    process of sending (for example, Throttle Mailings) and you invoke the
    ALL_NON_EXPORTED feature, Watson Campaign Automation will not include Sent events until it sends to all contacts. 

     
    Elements  SUPPRESSED Optional 

    Specify to receive Suppressed events.

    Note: Suppressed contacts are not included. If a mailing is in the
    process of sending (for example, Throttle Mailings) and you invoke the
    ALL_NON_EXPORTED feature, Watson Campaign Automation will 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, Watson Campaign Automation will not export their 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: including this element can greatly decrease the time to generate the metrics file and is recommended whenever metrics for deleted contacts are not required. 

     
    Optional Child Elements  COLUMNS Optional XML node used to request list columns to export for each contact.   
      Child Element  COLUMN     
        Child Element  NAME  Specifies the field name. 
    Example¬† <soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
    xmlns:ses=”SilverpopApi:EngageService.SessionHeader” xmlns:rep=”SilverpopApi:EngageService.Reporting”>
    <soapenv:Header>
    <ses:sessionHeader>
    <ses:sessionid>16FE7B75445E6C704707025B1B7BBEE5</ses:sessionid>
    </ses:sessionHeader>
    </soapenv:Header>
    <soapenv:Body>
    <rep:RawRecipientDataExport>
    <rep:EVENT_DATE_START>06/01/2009 00:00:00</rep:EVENT_DATE_START>
    <rep:EVENT_DATE_END>06/29/2009 23:59:00</rep:EVENT_DATE_END>
    <rep:EXPORT_FORMAT>0</rep:EXPORT_FORMAT>
    <rep:EMAIL>admin@yourorg.com</rep:EMAIL>
    <rep:MOVE_TO_FTP/>
    <rep:ALL_EVENT_TYPES/>
    <rep:EXCLUDE_DELETED/>
    <rep:INCLUDE_INBOX_MONITORING/>
    <rep:COLUMNS>
    <rep:COLUMN>
    <rep:NAME>CustomerID</rep:NAME>
    </rep:COLUMN>
    <rep:COLUMN>
    <rep:NAME>Address</rep:NAME>
    </rep:COLUMN>
    </rep:COLUMNS>
    </rep:RawRecipientDataExport>
    </soapenv:Body>
    </soapenv:Envelope> 
         
    Response  <RESULT>       
    Elements  SUCCESS  True if successful.     
    ¬† MAILING¬† XML nodes defining the user‚Äźcreated column name and value.¬† ¬† ¬†
      Child Element 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:Envelope xmlns=”SilverpopApi:EngageService.Reporting”
    xmlns:envelope=”http://schemas.xmlsoap.org/soap/envelope/”>
    <envelope:Header/>
    <envelope:Body>
    <RESULT>
    <SUCCESS>TRUE</SUCCESS>
    <MAILING>
    <JOB_ID>503537</JOB_ID>
    <FILE_PATH>Raw Recipient Data Export Jul 17 2009 09‚Äź28‚Äź37
    AM.zip</FILE_PATH>
    </MAILING>
    </RESULT>
    </envelope:Body>
    </envelope:Envelope> 
         
  2. A single file exports with the following columns populated for each event

    Column  Description   
    Recipient ID The ID of the contact associated with the event.  
    Recipient Type 

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

    Regular ‚Äď 0
    Forward ‚Äď 1
    Seed ‚Äď 3
    Inbox Monitoring ‚Äď 4

     

     
    Mailing ID  The ID of the Sent Mailing associated with the event.   
    Report ID¬† Depending on the type of mailing, you can assign Report IDs 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, there is a one‚Äźto‚Äźone relationship between a Report ID and Mailing ID.¬† ¬†
    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. 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.  
  3. 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
    AOL ‚Äď 1
    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
    Invalid Organization Email Domain ‚Äď 3
    Organization Suppression List ‚Äď 4
    Global Suppression ‚Äď 5
    Invalid Organization Email Local ‚Äď 6
    Frequency Control ‚Äď 7
    Database Level Suppression ‚Äď 8
    Query Level Suppression ‚Äď 9
    Mailing Level Suppression ‚Äď 10

     

    Suppressed

Join The Discussion

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