Message Analytics Export

API Set Name: messageanalyticsexport

• POST / messageanalyticsexport
  Make the export file available:
• Via Cordial UI
• Via FTP/SFTP
• Via Amazon S3
• Via Google Cloud Storage (GCS)
• JSON File Via FTP Download
• Example Request URIs
• Error Responses

API Description and Functional Purpose:

The message analytics export resource creates an export job to download and store a file of message analytics from the Cordial database to an external location. The exported file can be downloaded via Cordial UI, FTP/SFTP, sent to Amazon S3 bucket, and sent to Google Cloud Storage bucket.

Additional information:

• This resource uses the JSON request information to define the target host location of the file, the transport protocol, the external host login authentication information and the fields to include in the file.
• It is important to note that this resource is not a collection of exports, but is a resource that initiates export processing by creating an export job.
• Export status information is available through the "jobs" resource. To access the Jobs page via Cordial UI, click on the    icon at the top right of the application header.
• Export supports file types "CSV" and "JSON".
• Export files made available for download via the UI will be stored for 30 days from the date of the export.

POST /messageanalyticsexport

Parameters

* Required

"columnHeaders": [
{
"name": "_id",
"label": "Message ID"
},
{
"name": "name",
"label": "Message Name"
},
{
"name": "subject",
"label": "Message Subject"
},
{
"name": "tags",
"label": "Message Tags"
},
{
"name": "sendTime",
"label": "Sent Date"
},
{
"name": "totalSent",
"label": "Sent Total"
},
{
"name": "totalBounced",
"label": "Bounced Total"
},
{
"name": "bounceRate",
"label": "Bounce Rate"
},
{
"name": "bouncedHard",
"label": "Bounced Hard"
},
{
"name": "bouncedSoft",
"label": "Bounced Soft"
},
{
"name": "delivered",
"label": "Delivered total"
},
{
"name": "deliveryRate",
"label": "Delivered rate"
},
{
"name": "opensTotal",
"label": "Opens Total"
},
{
"name": "opensUnique",
"label": "Opens Unique"
},
{
"name": "openRate",
"label": "Open Rate"
},
{
"name": "clicksTotal",
"label": "Click Total"
},
{
"name": "clicksUnique",
"label": "Clicks Unique"
},
{
"name": "ctor",
"label": "Click To Open Ratio"
},
{
"name": "clickRate",
"label": "Click Rate"
},
{
"name": "complaintsTotal",
"label": "Complaints"
},
{
"name": "complaintRate",
"label": "Complaint Rate"
},
{
"name": "optoutsTotal",
"label": "Opt Outs"
},
{
"name": "optoutRate",
"label": "Opt Out Rate"
},
{
"name": "revenue",
"label": "Message Revenue"
},
{
"name": "totalPurchases",
"label": "Total Purchases"
},
{
"name": "aov",
"label": "Average Order Value"
},
{
"name": "messageKey",
"label": "Message Key"
},
{
"name": "messageType",
"label": "Message Type"
},
{
"name": "lastSendDate",
"label": "Last Sent Date"
}
]

Example JSON Requests

The following will initiate an export job of sent batch message analytics for March 25 into a CSV file that will be available via the UI on the Jobs page.

{
    "name": "batch_analytics_m25",
    "exportType": "csv",
    "destination": {
        "type": "aws"
    },
    "showHeader": true,
    "selected_timeframe_start": "2019-03-24T00:00:00.000Z",
    "selected_timeframe_end": "2019-03-25T23:59:59.999Z",
    "type": "batch"
}

The following will initiate an export job of sent batch message analytics for March 25 into a CSV file via FTP download.

{
    "name": "batch_analytics_m25",
    "exportType": "csv",
    "destination": {
        "type": "ftp",
        "server": "ftp.example.com",
        "port": 21,
        "username": "cordial@example.com",
        "password": "cordial",
        "path": "/folder"
    },
    "showHeader": true,
    "selected_timeframe_start": "2019-03-24T00:00:00.000Z",
    "selected_timeframe_end": "2019-03-25T23:59:59.999Z",
    "type": "batch"
}

The following will initiate an export job of sent batch message analytics for March 25 into a CSV file via the Amazon S3:

{
    "name": "batch_analytics_m25",
    "exportType": "csv",
    "destination": {
        "type": "s3",
        "aws_access_key_id": "A1234567890",
        "aws_secret_access_key": "B1234567890",
        "aws_bucket": "my_bucket",
        "aws_region": "us-west-2",
        "path": "/folder"
    },
    "showHeader": true,
    "selected_timeframe_start": "2019-03-24T00:00:00.000Z",
    "selected_timeframe_end": "2019-03-25T23:59:59.999Z",
    "type": "batch"
}

The following will initiate an export job of sent batch message analytics for March 25 into a CSV file via the Google Cloud Storage (GCS):

{
    "name": "batch_analytics_m25",
    "exportType": "csv",
    "destination": {
        "type": "gcs",
        "gcs_bucket": "bucketname",
        "path": "/folder"
    },
    "showHeader": true,
    "selected_timeframe_start": "2019-03-24T00:00:00.000Z",
    "selected_timeframe_end": "2019-03-25T23:59:59.999Z",
    "type": "batch"
}

The following will initiate an export job of all sent batch message click analytics into a JSON file via FTP download. Note that each record is returned as a separate line consisting of a single JSON object (not an array of JSON objects).

{
    "name": "batch_clicks_m25",
    "exportType": "json",
    "destination": {
        "type": "ftp",
        "server": "ftp.example.com",
        "port": 21,
        "username": "username@example.com",
        "password": "password",
        "path": "./"
    },
    "showHeader": true,
    "selected_timeframe_start": "2019-03-24T00:00:00.000Z",
    "selected_timeframe_end": "2019-03-25T23:59:59.999Z",
    "type": "batch",
    "columnHeaders": [
        {
            "name": "_id",
            "label": "Message ID"
        },
        {
            "name": "name",
            "label": "Message Name"
        },
        {
            "name": "subject",
            "label": "Subject"
        },
        {
            "name": "tags",
            "label": "Message Tags"
        },
        {
            "name": "sendTime",
            "label": "Sent Date"
        },
        {
            "name": "totalSent",
            "label": "Sent Total"
        },
        {
            "name": "clicksTotal",
            "label": "Click Total"
        },
        {
            "name": "clicksUnique",
            "label": "Clicks Unique"
        },
        {
            "name": "ctor",
            "label": "CTOR"
        }
    ]
}

The following will initiate an export job of sent automation message analytics aggregated and by message type and by totals for March 25 into a CSV file that will be available via the UI on the Jobs page.

Aggregate Results

{
   "name": "batch_analytics_m25", 
   "exportType": "csv", 
   "destination": { 
      "type": "aws" 
   }, 
   "showHeader": true, 
   "selected_timeframe_start": "2019-03-24T00:00:00.000Z", 
   "selected_timeframe_end": "2019-03-25T23:59:59.999Z", 
   "type": "automation",
   "rollupAutomations": true
}

Show results by message type and add totals row

{
   "name": "batch_analytics_m25", 
   "exportType": "csv", 
   "destination": { 
   "type": "aws" 
}, 
   "showHeader": true, 
   "selected_timeframe_start": "2019-03-24T00:00:00.000Z", 
   "selected_timeframe_end": "2019-03-25T23:59:59.999Z", 
   "type": "automation",
   "viewMode": "by_message_type",
   "includeTotalsRow": true
}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/messageanalyticsexport

Error Responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Message Analytics Export API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it is likely recorded within the Global API Error Responses page.