In This Section

Message Analytics Export

API Set Name: messageanalyticsexport

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.

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.
  • Export supports file type "CSV" and "JSON".
  • Export files in the UI will be stored for 30 days from the date of the export.

POST /messageanalyticsexport

Method URI Path
POST /messageanalyticsexport
Creates an export job using the JSON body information.

Parameters

* Required

Parameter Type Description Example
name string Defines the name of file for destination type FTP or SFTP. BatchAnalyticsExport
*exportType string Defines the type of the file to be exported.
Possible Values:
CSV, JSON		 json
selected_timeframe_start string Start date and time of selected timeframe to be exported. 2018-03-24T00:00:00.000Z
selected_timeframe_end string End date and time of selected timeframe to be exported. 2018-03-24T23:59:59.999Z
type string Defines the message type to be exported.
Possible Values:
batch, automation, both		 both
selected_message_name string Defines the name of the message to be exported. April Promo
selected_message_tags array

Defines the message tags to be exported.

 ["welcome","promo"]
selected_message_tags_operator string Defines the message tags operator.
Possible Values:
any, all		 any
showHeader boolean For use when export type is "CSV" to determine if first row displays column names.
Possible Values:
true, false		 true

Destination
Note: Destination type "aws" should be used if file is to be downloaded only from the UI.
If Destination type "S3", API calls should be made using /v2/messageanalyticsexport.
type string Defines the destination type.
Possible Values:
aws, ftp, sftp, s3		 sftp

server (required if type is ftp or sftp)

 string Domain or IP address of the SFTP server. sftp.example.com
port (required if type is ftp or sftp) number Defines the port number for the FTP or SFTP server. 22
username (required if type is ftp or sftp) string Defines the username for FTP or SFTP authentication. username
password (required if type is ftp or sftp) string Defines the password for FTP or SFTP authentication. password
aws_access_key_id (required if type is s3) string Defines the public AWS id. A1234567890
aws_secret_access_key(required if type is S3) string Defines the secret AWS key. B1234567890
aws_bucket (required if type is S3) string Defines the AWS bucket name. bucket
aws_region (required if type is S3) string Defines the AWS region. us-west-2
path (required if type is ftp, sftp or S3) string If type is S3: path to folder and file. If type is FTP or SFTP: path to folder. S3: /folder/analyticsExport.csv FTP: /folder

ColumnHeaders
For use when explicitly defining the output column headers. If no column headers are provided, all available column headers will be included in the CSV output file:

"columnHeaders": [
{
"name": "_id",
"label": "Message ID"
},
{
"name": "name",
"label": "Message Name"
},
{
"name": "subject",
"label": "Subject"
},
{
"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": "CTOR"
},
{
"name": "complaintsTotal",
"label": "Complaints"
},
{
"name": "complaintRate",
"label": "Complaint Rate"
},
{
"name": "optoutsTotal",
"label": "Opt Outs"
},
{
"name": "optoutRate",
"label": "Opt Out Rate"
},
{
"name": "revenue",
"label": "Revenue"
},
{
"name": "totalPurchases",
"label": "Total Purchases"
},
{
"name": "aov",
"label": "AOV"
}
]
name string Name of column in Cordial system. ctor
label string Label for column which will be represented in file. Click to Open Rate

Example JSON Requests

The following will initiate an export job of all sent batch message analytics into a CSV file that will be available to be downloaded via the UI.

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

The following will initiate an export job of all sent batch message analytics into a CSV file via an ftp download.

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

The following will initiate an export job of all sent batch message click analytics into a JSON file via an 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_30days",
  "exportType": "json",
  "destination": {
    "type": "ftp",
    "server": "ftp.example.com",
    "port": 21,
    "username": "username@example.com",
    "password": "password",
    "path": "./"
  },
  "showHeader": true,
  "selected_timeframe_start": "2018-03-24T00:00:00.000Z",
  "selected_timeframe_end": "2018-03-24T23:59:59.999Z",
  "type": "batch",
  "columnHeaders": [
{
"name": "_id",
"label": "Message ID"
},
{
"name": "name",
"label": "Message Name"
},
{
"name": "subject",
"label": "Subject"
},
{
"name": "sendTime",
"label": "Sent Date"
},
{
"name": "totalSent",
"label": "Sent Total"
},
{
"name": "clicksTotal",
"label": "Click Total"
},
{
"name": "clicksUnique",
"label": "Clicks Unique"
},
{
"name": "ctor",
"label": "CTOR"
}
]
}

Example Request URIs

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

http://<path>/messageanalyticsexport

 

Related articles

Comments

0 comments

Please sign in to leave a comment.