# How can we help?
## 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](https://support.cordial.com/hc/en-us/articles/115003902411) and [automated](https://support.cordial.com/hc/en-us/articles/360000061911) 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 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](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization.
- [Learn more about Cordial API authentication here](httpss://support.cordial.com/hc/en-us/articles/203885498-RESTful-API-summary-and-usage#authentication).
## Methods, parameters, and examples
- [POST/v2/messageanalyticsexport](https://support.cordial.com/hc/en-us/articles/360003029691-Message-analytics-export-API#postContactActivityExport)
## POST/v2/messageanalyticsexport
| Method | URL Path |
| --- | --- |
| POST | /v2/messageanalyticsexport |
| Creates a message analytics export job using the JSON body information. |
### Required Parameters
| 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** | object | **Required if SFTP, FTP, S3, or Google Cloud Storage (GCS) is the destination.**
- 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 | string | Domain or IP address for the FTP/SFTP server. | sftp.example.com |
| port | number | Defines the port number for the FTP or SFTP server. | 22 |
| username | string | Defines the username for FTP or SFTP authentication. | username |
| password | string | Defines the password for FTP or SFTP authentication. | password |
| aws_access_key_id | string | Defines the public AWS access key ID. | A1234567890 |
| aws_secret_access_key | string | Defines the secret AWS access key. | B1234567890 |
| aws_bucket | string | Defines the AWS bucket name. | bucket |
| aws_region | string | Defines the AWS region. | us-west-2 |
| gcs_bucket | string | Defines the GCS bucket name. | bucketname |
| path | 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 |
### Examples
### 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](https://support.cordial.com/hc/en-us/articles/115008871127).
```json
{
"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.
```json
{
"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.
```json
{
"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"
}
```
### 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).
```json
{
"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).
```json
{
"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](https://support.cordial.com/hc/en-us/articles/115008871127).
```json
{
"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
}
```
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.
```json
{
"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 JSON object includes all available analytics column headers. Remove any fields as desired.
```json
{
"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": "clicksTotal", "label": "Click Total"},
{"name": "clicksUnique", "label": "Clicks Unique"},
{"name": "ctor", "label": "Click To Open Ratio"}
]
}
```
The following URL in conjunction with the JSON will perform the POST.
`https:///v2/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](https://support.cordial.com/hc/en-us/articles/4402427843597-Global-API-Error-Responses) page.
| errorKey | Message | Modifications |
| --- | --- | --- |
| MESSAGE_ANALYTICS_EXPORT_TIMEFRAME_END_BEFORE_TIMEFRAME_START | selected_timeframe_end' cannot be in past in comparison with 'selected_timeframe_start' | The provided start time needs to occur before the provided end time. |
| MESSAGE_ANALYTICS_EXPORT_MESSAGE_TAGS_MESSAGE_NAME_CONFLICT | Please use only one from existing filters 'selected_message_tags' or 'selected_message_name' | Either a specific message or message tags may be used. |
| MESSAGE_ANALYTICS_EXPORT_FILTER_MESSAGE_TAGS_OPERATOR_IS_NOT_SUPPORTED | Not supported value for selected_message_tags_operator. | The possible values for this key are: any or all.