Overview

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

API set name: messageanalyticsexport

Message experiment results are not available for export via the message analytics export API endpoint. Experiment results can be exported for individual batch and automated messages in the UI.

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's important to note that this resource is not a collection of exports. This endpoint initiates export processing by creating an export job.
• Export status information is available through the jobs API and on the the Jobs page in the UI.
• 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.

Authentication

Cordial's core APIs use HTTPS Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

• Learn more about Cordial API authentication here.

Methods, parameters, and examples

• POST/v2/messageanalyticsexport

POST/v2/messageanalyticsexport

• * Required

  Parameter	Type	Description	Example
  name	string	Defines the export job name. If provided, this value will be displayed next to the job ID on the Jobs Widget page.	BatchAnalyticsExport
  fileName	string	Defines the export file name.	march_batch_export
  * exportType	string	Defines the type of the file to be exported. Possible values: csv, json (lowercase)	JSON
  selected_timeframe_start	string	Start date and time of selected time period to be exported.	2018-03-24T00:00:00.000Z
  selected_timeframe_end	string	End date and time of selected time period to be exported.	2018-03-24T23:59:59.999Z
  selected_channel	string	Filter export results by the messaging channel. Note that some of your channels may have custom keys.	email
  type	string	Defines the message type to be exported. Possible values: batch, automation, orchestration, both (deprecated), all	both
  selected_orchestration_name	string	The name of the orchestration to be exported. Not available when type is batch.	Birthday Series
  selected_orchestration_id	string	The ID of the orchestration to be exported. Not available when type is batch.	710bd8c1351e20754712ac01
  selected_message_name	string	The name of the specific message to be exported. Not available when type is batch.	April Promo
  selected_message_tags	array	Export analysis for messages with specific message tags. Not available when type is batch.	["welcome","promo"]
  selected_message_tags_operator	string	Export analysis for messages with any or all of the provided message tags. Possible values: any, all	any
  selected_audience_names	array	List of audience names used in the report.	["all_contacts"]
  selected_audience_ids	array	List of audience IDs used in the report.	["5d0bc016a0826a7e6f"]
  showHeader	boolean	For use when export type is "CSV" to determine if first row will display column names. Possible values: true, false	true
  viewMode	string	Filters message performance results by day/hour, by message type, or all messages as a total. Possible values: by_message, by_message_type, as_total	by_message_type
  includeTotalsRow	boolean	For use when export type is "CSV" to determine if last row will display an aggregate total. Possible values: true, false	true
  rollupAutomations	boolean	Aggregates automation messages with the same message ID into a single row. Possible values: true, false	true
  * destination Note: This parameter is only required if SFTP, FTP, S3, or Google Cloud Storage (GCS) is the destination. Note: Use destination type "aws" when downloading the file via 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, GCS	sftp
  server (required if type is FTP or SFTP)	string	Domain or IP address for the FTP/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 access key ID.	A1234567890
  aws_secret_access_key (required if type is S3)	string	Defines the secret AWS access 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
  gcs_bucket	string	Defines the GCS bucket name.	bucketname
  path (required if type is FTP, SFTP, S3 or GCS)	string	If type is S3: path to folder and file. If type is FTP, SFTP, or GCS: path to folder.	S3: /folder/analyticsExport.csv FTP: /folder, GCS: /folder
  columnHeaders Use the columnHeaders field when explicitly defining which column headers are returned in the CSV file. If no column headers are specified, all available column headers will be included in the CSV file. The order of column headers will always remain the same. Any new column headers added by Cordial will be added to the end of the CSV file. See example columnHeaders tab above.
  name	string	Data field name as it appears in the Cordial database.	ctor
  label	string	Custom column header label to accompany the field name.	Click to Open Rate

• UI - CSV

  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": "2025-03-24T00:00:00.000Z",
      "selected_timeframe_end": "2025-03-25T23:59:59.999Z",
      "type": "batch"
  }

  FTP - CSV

  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": "2025-03-24T00:00:00.000Z",
      "selected_timeframe_end": "2025-03-25T23:59:59.999Z",
      "type": "batch"
  }
  

  Amazon S3

  The following will initiate an export job of sent batch message analytics for March 25 into a CSV file via 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": "2025-03-24T00:00:00.000Z",
      "selected_timeframe_end": "2025-03-25T23:59:59.999Z",
      "type": "batch"
  }
  

  We recommend omitting the trailing slash right after your S3 path name to avoid duplicate slashes being added by default. For example, use /folder instead of /folder/.

  Google Cloud Storage

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

  Your Google Cloud Storage integration must be enabled in the Cordial Marketplace.

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

  FTP - JSON

  The following will initiate an export job of all sent batch message click analytics into a JSON file via FTP download.

  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": "2025-03-24T00:00:00.000Z",
      "selected_timeframe_end": "2025-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"
          }
      ]
  }

  Additional examples

  The following will initiate an export job of sent automation message analytics aggregated by message type and 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": "2025-03-24T00:00:00.000Z", 
     "selected_timeframe_end": "2025-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": "2025-03-24T00:00:00.000Z", 
     "selected_timeframe_end": "2025-03-25T23:59:59.999Z", 
     "type": "automation",
     "viewMode": "by_message_type",
     "includeTotalsRow": true
  }

  The following will initiate an export job of sent batch message analytics aggregated by audience names into a CSV file that will be available on the Jobs page in the UI.

  {
    	"name": "API-group-by-audience",
    	"exportType": "csv",
  	"destination": {
  	    "type": "ftp",
  	    "server": "ftp.example.com",
  	    "port": 21,
  	    "username": "cordial@example.com",
  	    "password": "cordial",
  	    "path": "/folder"
  	},
  	"showHeader": true,
  	"selected_timeframe_start": "2025-03-24T00:00:00.000Z",
  	"selected_timeframe_end": "2025-03-25T23:59:59.999Z",
  	"type": "batch",
  	"selected_audience_names": ["all_contacts", "another_audience_name"]
  }

  The following will initiate an export job of sent batch message analytics aggregated by audience IDs into a CSV file that will be available on the Jobs page in the UI.

  You can't use the audience name and audience ID requests at the same time. Either name or ID can be used for one request.

  {
    	"name": "API-group-by-audience",
    	"exportType": "csv",
  	"destination": {
  	    "type": "ftp",
  	    "server": "ftp.example.com",
  	    "port": 21,
  	    "username": "cordial@example.com",
  	    "password": "cordial",
  	    "path": "/folder"
  	},
  	"showHeader": true,
  	"selected_timeframe_start": "2025-03-24T00:00:00.000Z",
  	"selected_timeframe_end": "2025-03-25T23:59:59.999Z",
  	"type": "batch",
  	"selected_audience_ids": ["5d0bc016a0826a7e6f049401", "7d98f779661cea7b06dc918e9198534b"]
  }

• The following JSON object includes all available analytics column headers. Remove any fields as desired.

  {
   "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"
     },
     {
       "name": "opensTotalAdjusted",
       "label": "Opens Total (adjusted)"
     },
     {
       "name": "opensUniqueAdjusted",
       "label": "Opens Unique (adjusted)"
     },
     {
       "name": "openRateAdjusted",
       "label": "Open Rate (adjusted)"
     }
   ]
  }
  

• The following URL in conjunction with the JSON will perform the POST.

  https://<path>/v2/messageanalyticsexport

Test in Swagger

You can access and test Cordial's APIs in Swagger.

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.