swagger: '2.0'
info:
title: Emarsys Core API - Contact and email data endpoint batch
description: In this batch you may find endpoints related to contact and email data.
version: v2
host: api.emarsys.net
basePath: /api
schemes:
- https
paths:
/v2/contact/getchanges:
post:
summary: Export Updated Contacts
description: |-
Exports the specified fields of contacts that have been modified within a certain time period. The changes must come from the specified form or API source to be included.
| SOURCE | |UPDATED FIELDS | |
| --- | --- | --- | --- |
| | **Email address** | **Opt-in status** | **Other** |
| **Forms (`register.php`)** | contact exported | contact exported | contact exported |
| **API: [Contact update](reference/openapi.json/paths/~1v2~1contact~1/put)** | contact exported | contact exported | contact exported |
| **[Data import](https://help.emarsys.com/hc/en-us/articles/360013356254-Overview-Data-Import-Overview)** | contact **not** exported | contact **not** exported | contact **not** exported |
**Important:**
The results are saved as a CSV file that you can access in multiple ways.
- Exports flagged as `local` are stored on the Emarsys server that you can download via WebDAV or an API call.
- Exports flagged as `sftp` can be accessed via SFTP.
**Implementation**
You can implement this method as follows:
-Poll the [Check Export Status](reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint to track the export status. When done, access the file at the [Download Export Data](reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get) endpoint.
- Set the `notification_url` parameter to implement a callback mechanism. When the export is ready, a request is sent to the provided URL with the same payload as the [Check Export Status](reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response. Failures are retried 5 times, with a one-minute wait between each try.
**Notes**
- As we are using a proxy for SFTP traffic, it is not necessary to whitelist any IPs on our side.
- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or SFTP access, contact Emarsys support.
**Example**
```csv
user_id;First Name;Last Name;E-Mail;Company
8019189;user3;test_import;test1@emarsys.com;
49036141;user3;test_import;test1@emarsys.com;
50123406;user3;test_import;test1@emarsys.com;
85600590;user3;test_import;test1@emarsys.com;
```
operationId: exportChangedContacts
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
distribution_method:
type: string
enum:
- sftp
- local
description: |-
The method to access the export.
**Note:** If the `sftp` option is selected, you must provide the SFTP configuration settings in the `ftp_settings` parameter.
origin:
type: string
enum:
- form
- api
- all
description: Indicates which platform triggered the change.
origin_id:
type: string
description: |-
The origin identifier. The default value *0* indicates no source. Other values specify a custom contact source.
| Origin Type | Identifier |
| --- | --- |
| Form | Form identifier |
| API | *0* |
default: 0
time_range:
type: array
description: |-
A two-element array that contains the *start date* and *end date* values.
**Accepted format:** YYYY-MM-DD
**datetime** format is available upon request, turn to support to enable it.
items:
type: string
contact_fields:
type: array
description: |-
The field identifiers to include in the export. The following fields cannot be exported:
| Field Identifier | Description |
| --- | --- |
| 27 | Average length of visit |
| 28 | Average pages per day |
| 29 | Last mail received |
| 32 | User status |
| 33 | Contact source |
minItems: 1
maxItems: 20
items:
type: integer
delimiter:
type: string
enum:
- ','
- ;
description: The delimiter character to be used in the CSV export.
default: ','
add_field_names_header:
type: integer
enum:
- 0
- 1
description: Determines whether to insert a header row into the CSV file.
default: 1
language:
type: string
description: 'The language of the export. The default is the account’s language. For the list of language codes, see [language codes](docs/appendix/language-codes.md).'
pattern: '^[a-z]{2}'
minLength: 2
maxLength: 2
ftp_settings:
type: object
description: 'Mandatory distribution settings parameter, if the `distribution_method` is `ftp`. For `local`, these settings are ignored.'
properties:
host:
type: string
description: The address of the FTP host.
format: uri
port:
type: string
description: The port of the FTP host.
username:
type: string
description: The login user name.
password:
type: string
description: The login password.
folder:
type: string
description: The folder on the FTP that contains the export file. Optional.
notification_url:
type: string
description: |-
Sends a request to the provided URL when the export is ready.
Set this parameter to implement a callback mechanism instead of polling the [Check Export Status](reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint.
**Note:** The payload is the same as the [Check Export Status](reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response.
format: uri
required:
- distribution_method
- origin
- origin_id
- time_range
- contact_fields
x-examples:
- distribution_method: sftp
origin: form
origin_id: '123'
time_range:
- '2012-02-09'
- '2012-04-02'
contact_fields:
- 1
- 3
- 106533
delimiter: ;
add_field_names_header: 1
language: en
ftp_settings:
host: 'https://www.example.com/'
port: '1234'
username: user
password: pass
folder: path/of/a/folder
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
data:
type: object
description: The requested data.
properties:
id:
type: integer
description: 'The export identifier that you can use to poll export status ([Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get)) and download the export file ([Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get)).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
/v2/email/getcontacts:
post:
summary: Export a Contact List
description: |-
Exports the specified fields of contacts from a contact list as a CSV file.
**Important:**
The results are saved as a CSV file that you can access in multiple ways.
- Exports flagged as `local` are stored on the Emarsys server that you can download via WebDAV or an API call.
- Exports flagged as `sftp` can be accessed via SFTP.
- Exports flagged as `mail` are sent to the specified address when ready.
**Implementation**
You can implement this method as follows:
- Poll the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint to track the export status. When done, access the file at the [Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get) endpoint.
- Set the `notification_url` parameter to implement a callback mechanism. When the export is ready, a request is sent to the provided URL with the same payload as the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response. Failures are retried 5 times, with a one-minute wait between each try.
**Notes**
- As we are using a proxy for FTP traffic, it is not necessary to whitelist any IPs on our side.
- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or (S)FTP access, contact Emarsys support.
**Example**
```csv
First Name;Last Name;E-mail;Opt-in
Fname_1;Lname_1;testuser@example.com;True
Fname_2;Lname_2;testuser@example.com;True
Fname_3;Lname_3;testuser@example.com;True
Fname_4;Lname_4;testuser@example.com;True
```
> **Important:** Due to limitations of API specification languages, dynamic keys are not yet supported in query strings on the interactive demo page (**Try it out**). We are working on this issue.
**Tip:** You can use the [Postman Collection](https://raw.githubusercontent.com/emartech/developer-hub-public-assets/master/resources/EmarsysV2PostmanCollection.json) to test the endpoint.
operationId: exportContactList
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
distribution_method:
type: string
enum:
- ftp
- sftp
- local
- mail
description: |-
The method to access the export.
**Notes**
- If the `sftp` option is selected, provide the mandatory SFTP configuration settings in the `sftp_settings` parameter.
- If the `mail` option is selected, provide the mandatory email address in the `distribution_email_address` parameter.
contactlist:
type: integer
description: The identifier of the contact list to be exported.
contact_fields:
type: array
description: |-
The field identifiers to include in the export. The following fields cannot be exported:
| Field Identifier | Description |
| --- | --- |
| 27 | Average length of visit |
| 28 | Average pages per day |
| 29 | Last mail received |
| 32 | User status |
| 33 | Contact source |
minItems: 1
maxItems: 20
items:
type: integer
delimiter:
type: string
enum:
- ','
- ;
description: The delimiter character to be used in the CSV export.
default: ','
add_field_names_header:
type: integer
enum:
- 0
- 1
description: Determines whether to insert a header row into the CSV file.
default: 1
language:
type: string
description: 'The language of the export. The default is the account’s language. For the list of language codes, see [language codes](docs/appendix/language-codes.md).'
pattern: '^[a-z]{2}'
minLength: 2
maxLength: 2
ftp_settings:
type: object
description: 'Mandatory distribution settings parameter, if the `distribution_method` is `sftp`. For `local`, these settings are ignored.'
properties:
host:
type: string
port:
type: string
username:
type: string
password:
type: string
folder:
type: string
email:
type: string
description: The email address to send the export to if the distribution method is `mail`.
format: email
notification_url:
type: string
description: |-
Sends a request to the provided URL when the export is ready.
Set this parameter to implement a callback mechanism instead of polling the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint.
**Note:** The payload is the same as the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response.
required:
- distribution_method
- contactlist
- contact_fields
x-examples:
- distribution_method: ftp
contactlist: 111111111
contact_fields:
- 1
- 3
- 106533
delimiter: ;
add_field_names_header: 1
language: en
ftp_settings:
host: www.example.com
port: '1234'
username: user
password: pass
folder: path/of/a/folder
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
data:
type: object
description: The requested data.
properties:
id:
type: integer
description: 'The export identifier that you can use to poll export status ([Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get)) and download the export file ([Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get)).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
/v2/export/filter:
post:
summary: Export a Segment
description: |-
Exports the specified fields of contacts from a segment as a CSV file.
**Important:**
The results are saved as a CSV file that you can access in multiple ways.
- Exports flagged as `local` are stored on the Emarsys server that you can download via WebDAV or an API call.
- Exports flagged as `ftp` can be accessed via FTP.
- Exports flagged as `sftp` can be accessed via SFTP.
- Exports flagged as `mail` are sent to the specified address when ready.
**Implementation**
ou can implement this method as follows:
- Poll the [Check Export Status](https://dev.emarsys.com/docs/core-api-reference/branches/main/4qd2h7o1jnxmd-check-export-status) endpoint to track the export status. When done, access the file at the [Download Export Data](https://dev.emarsys.com/docs/core-api-reference/branches/main/2ndhiv5xao5ar-download-export-data) endpoint.
- Set the `notification_url` parameter to implement a callback mechanism. When the export is ready, a request is sent to the provided URL with the same payload as the [Check Export Status](https://dev.emarsys.com/docs/core-api-reference/branches/main/4qd2h7o1jnxmd-check-export-status) response. Failures are retried 5 times, with a one-minute wait between each try.
**Notes**
- As we are using a proxy for FTP traffic, it is not necessary to whitelist any IPs on our side.
- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or (S)FTP access, contact Emarsys support.
**Example**
An example contact list export including first name, last name, email address and opt-in status results in the following CSV:
```csv
First Name;Last Name;E-mail;Opt-in
Fname_1;Lname_1;testuser@example.com;True
Fname_2;Lname_2;testuser@example.com;True
Fname_3;Lname_3;testuser@example.com;True
Fname_4;Lname_4;testuser@example.com;True
```
operationId: exportSegment
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
distribution_method:
type: string
enum:
- ftp
- sftp
- local
- mail
description: |-
The method to access the export.
**Notes**
- If the `ftp` option is selected, provide the mandatory FTP configuration settings in the `ftp_settings` parameter.
- If the `mail` option is selected, provide the mandatory email address in the `distribution_email_address` parameter.
filter:
type: integer
description: The identifier of the contact list to be exported.
contact_fields:
type: array
description: |-
The field identifiers to include in the export. The following fields cannot be exported:
| Field Identifier | Description |
| --- | --- |
| 27 | Average length of visit |
| 28 | Average pages per day |
| 29 | Last mail received |
| 32 | User status |
| 33 | Contact source |
minItems: 1
maxItems: 20
items:
type: integer
delimiter:
type: string
enum:
- ','
- ;
description: The delimiter character to be used in the CSV export.
default: ','
add_field_names_header:
type: integer
enum:
- 0
- 1
description: Determines whether to insert a header row into the CSV file.
default: 1
language:
type: string
description: 'The language of the export. The default value is the language setting of the administrator called `admin` in the account. For the list of language codes, see [language codes](docs/appendix/language-codes.md).'
pattern: '^[a-z]{2}'
minLength: 2
maxLength: 2
ftp_settings:
type: object
description: 'Mandatory distribution settings parameter, if the `distribution_method` is `ftp`. For `local`, these settings are ignored.'
properties:
host:
type: string
port:
type: string
username:
type: string
password:
type: string
folder:
type: string
email:
type: string
description: |-
The email address where the export is sent if 'distribution_method' is set to `mail`.
**Note:** In such a scenario, this parameter is mandatory.
format: email
notification_url:
type: string
description: |-
Sends a request to the provided URL when the export is ready.
Set this parameter to implement a callback mechanism instead of polling the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint.
**Note:** The payload is the same as the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response.
required:
- distribution_method
- filter
- contact_fields
x-examples:
- distribution_method: ftp
filter: 111111111
contact_fields:
- 1
- 3
- 106533
delimiter: ;
add_field_names_header: 1
language: en
ftp_settings:
host: www.example.com
port: '1234'
username: user
password: pass
folder: path/of/a/folder
distribution_email_address: john@example.com
notification_url: 'https://www.example.com'
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
data:
type: object
description: The requested data.
properties:
id:
type: integer
description: 'The export identifier that you can use to poll export status ([Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get)) and download the export file ([Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get)).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
/v2/contact/getregistrations:
post:
summary: Export Contact Registrations
description: |-
Exports the specified fields of contacts registered through an Emarsys form within the specified time period as a CSV file.
**Tip:** If you want to export registrations from other sources, use the [Export Updated Contacts](/reference/openapi.json/paths/~1v2~1contact~1getchanges/post) endpoint.
**Important:**
The results are saved as a CSV file that you can access in multiple ways.
- Exports flagged as `local` are stored on the Emarsys server that you can download via WebDAV or an API call.
- Exports flagged as `sftp` can be accessed via SFTP.
**Implementation**
ou can implement this method as follows:
- Poll the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint to track the export status. When done, access the file at the [Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get) endpoint.
- Set the `notification_url` parameter to implement a callback mechanism. When the export is ready, a request is sent to the provided URL with the same payload as the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response. Failures are retried 5 times, with a one-minute wait between each try.
**Notes**
- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or SFTP access, contact Emarsys support.
**Example**
```csv
user_id;First Name;Last Name;E-Mail;Company;last update
135369573;user3;test_import;test1@emarsys.com;;
171879718;user3;test_import;test1@emarsys.com;;
183453150;user3;test_import;test1@emarsys.com;;
188925627;user3;test_import;test1@emarsys.com;;
```
operationId: exportContactRegistrations
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
distribution_method:
type: string
enum:
- local
- sftp
description: |-
The method to access the export.
**Note:** If the `ftp` option is selected, provide the mandatory FTP configuration settings in the `ftp_settings` parameter.
contactlist:
type: integer
description: The identifier of the contact list to filter the results.
time_range:
type: array
description: |-
A two-element array that contains the *start date* and *end date* values.
**Accepted format:** YYYY-MM-DD HH-SS
minItems: 2
maxItems: 2
items:
type: string
pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}'
with_timestamp:
type: integer
enum:
- 0
- 1
description: Determines whether the registration timestamp is included in the export.
default: 1
contact_fields:
type: array
description: |-
The field identifiers to include in the export. The following fields cannot be exported:
| Field Identifier | Description |
| --- | --- |
| 27 | Average length of visit |
| 28 | Average pages per day |
| 29 | Last mail received |
| 32 | User status |
| 33 | Contact source |
minItems: 1
maxItems: 20
items:
type: integer
delimiter:
type: string
enum:
- ','
- ;
description: The delimiter character to be used in the CSV export.
default: ','
add_field_names_header:
type: integer
enum:
- 0
- 1
description: Determines whether to insert a header row into the CSV file.
default: 1
language:
type: string
description: 'The language of the export. The default is the account’s language. For the list of language codes, see [language codes](docs/appendix/language-codes.md).'
pattern: '^[a-z]{2}'
minLength: 2
maxLength: 2
sftp_settings:
type: object
description: 'Mandatory distribution settings parameter, if the `distribution_method` is `sftp`. For `local`, these settings are ignored.'
properties:
host:
type: string
port:
type: string
username:
type: string
password:
type: string
folder:
type: string
notification_url:
type: string
description: |-
Sends a request to the provided URL when the export is ready.
Set this parameter to implement a callback mechanism instead of polling the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint.
**Note:** The payload is the same as the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response.
required:
- distribution_method
- time_range
- contact_fields
x-examples:
- distribution_method: ftp
contactlist: 111111111
time_range:
- '2012-02-09'
- '2012-04-02'
contact_fields:
- 1
- 3
- 106533
delimiter: ;
add_field_names_header: 1
language: en
ftp_settings:
host: www.example.com
port: '1234'
username: user
password: pass
folder: path/of/a/folder
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
data:
type: object
description: The requested data.
properties:
id:
type: integer
description: 'The export identifier that you can use to poll export status ([Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get)) and download the export file ([Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get)).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
/v2/email/getresponses:
post:
summary: Export Responses
description: |-
Exports the specified fields of contacts who responded to an email within a certain time period as a CSV file.
**Important:**
The results are saved as a CSV file that you can access in multiple ways.
- Exports flagged as `local` are stored on the Emarsys server that you can download via WebDAV or an API call.
- Exports flagged as `sftp` can be accessed via SFTP.
**Implementation**
ou can implement this method as follows:
- Poll the [Check Export Status](https://dev.emarsys.com/docs/core-api-reference/4qd2h7o1jnxmd-check-export-status) endpoint to track the export status. When done, access the file at the [Download Export Data](https://dev.emarsys.com/docs/core-api-reference/2ndhiv5xao5ar-download-export-data) endpoint.
- Set the `notification_url` parameter to implement a callback mechanism. When the export is ready, a request is sent to the provided URL with the same payload as the [Check Export Status](https://dev.emarsys.com/docs/core-api-reference/4qd2h7o1jnxmd-check-export-status) response. Failures are retried 5 times, with a one-minute wait between each try.
**Notes**
- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or SFTP access, contact Emarsys support.
**Example**
```csv
user_id;First Name;Last Name;E-Mail;Campaign title;Link title;Url;source
287705659;user3;test_import;test1@emarsys.com;VisualCMS_2015_04_09_10_05_03;;www.emarsys.com;click
287705659;user3;test_import;test1@emarsys.com;RSS_2015_04_09_10_05_03;;www.google.com.com;click
287705659;user3;test_import;test1@emarsys.com;AC_recurring_2015_04_09_10_05_03;;;open
```
operationId: exportResponses
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
distribution_method:
type: string
enum:
- ftp
- local
description: |-
The method to access the export.
**Note:** If the `ftp` option is selected, you must provide the FTP configuration settings in the `ftp_settings` parameter.
time_range:
type: array
description: |-
A two-element array that contains the *start date* and *end date* values.
**Accepted format:** YYYY-MM-DD HH:MM:SS
**Please note** that the *start date* set here may not be earlier than 1970-01-02 00:00:00, otherwise an error message will be thrown.
items:
type: string
contact_fields:
type: array
description: |-
The field identifiers to include in the export. The following fields cannot be exported:
| Field Identifier | Description |
| --- | --- |
| 27 | Average length of visit |
| 28 | Average pages per day |
| 29 | Last mail received |
| 32 | User status |
| 33 | Contact source |
minItems: 1
maxItems: 20
items:
type: integer
sources:
type: array
description: The source of the email response.
items:
type: string
enum:
- trackable_links
- registration_forms
- tell_a_friend
- contact_us
- change_profile
- unsubscribe
- mail_open
- complaint
analysis_fields:
type: array
description: |-
The contact behaviors to analyse based on specific field types of the email campaign.
**Accepted values:**
| Value | Description |
| --- | --- |
| 1 | Campaign title |
| 2 | Section header |
| 3 | Section group |
| 4 | Link title |
| 5 | URL |
| 8 | Time |
| 12 | Campaign identifier |
| 13 | Version name |
| 14 | Campaign category |
| 15 | Link category |
uniqueItems: true
items:
type: integer
email_id:
type: integer
description: The identifier of the email campaign. Returns the contact's responses to the email.
contactlist:
type: integer
description: The identifier of the contact list to filter the results.
delimiter:
type: string
enum:
- ','
- ;
description: The delimiter character to be used in the CSV export.
default: ','
add_field_names_header:
type: integer
enum:
- 0
- 1
description: Determines whether to insert a header row into the CSV file.
default: 1
language:
type: string
description: 'The language of the export. The default is the account’s language. For the list of language codes, see [language codes](docs/appendix/language-codes.md).'
pattern: '^[a-z]{2}'
minLength: 2
maxLength: 2
sftp_settings:
type: object
description: 'Mandatory distribution settings parameter, if the `distribution_method` is `sftp`. For `local`, these settings are ignored.'
properties:
host:
type: string
description: The address of the FTP host.
format: uri
port:
type: string
description: The port of the FTP host.
username:
type: string
description: The login user name.
password:
type: string
description: The login password.
folder:
type: string
description: The folder on the FTP that contains the export file. Optional.
notification_url:
type: string
description: |-
Sends a request to the provided URL when the export is ready.
Set this parameter to implement a callback mechanism instead of polling the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint.
**Note:** The payload is the same as the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response.
format: uri
required:
- distribution_method
- time_range
- contact_fields
- sources
- analysis_fields
x-examples:
- distribution_method: ftp
sources:
- trackable_links
email_id: 89268
time_range:
- '2012-02-09'
- '2014-08-13'
contact_fields:
- 1
- 3
analysis_fields:
- 5
- 8
- 15
delimiter: ;
add_field_names_header: 1
language: en
ftp_settings:
host: 'https://www.example.com/'
port: '21'
username: user
password: pass
folder: public_html/bonus/full
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
data:
type: object
description: The requested data.
properties:
id:
type: integer
description: 'The export identifier that you can use to poll export status ([Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get)) and download the export file ([Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get)).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
'/v2/export/{exportId}':
get:
summary: Check Export Status
description: |-
Returns information about an export, including its status, type, and output settings.
**Important:** In the exports, the created column is in Vienna timezone. Vienna timezone is UTC+2 in summertime but with Daylight Saving in wintertime it changes to UTC+1). Bear in mind that UTC does not observe Daylight Saving Time (unlike GMT).
**Note:** This endpoint tracks the status of an asynchronous operation using a job identifier. You can initiate an export job and get the identifier at the following endpoints:
- [Export Updated Contacts](/reference/openapi.json/paths/~1v2~1contact~1getchanges/post)
- [Export a Contact List](/reference/openapi.json/paths/~1v2~1email~1getcontacts/post)
- [Export a Segment](/reference/openapi.json/paths/~1v2~1export~1filter/post)
- [Export Responses](/reference/openapi.json/paths/~1v2~1email~1getresponses/post)
operationId: checkExportStatus
produces:
- application/json
parameters:
- name: exportId
in: path
description: 'The export identifier returned at the [Export Updated Contacts](/reference/openapi.json/paths/~1v2~1contact~1getchanges/post) endpoint.'
required: true
type: integer
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
data:
type: object
description: The requested data.
properties:
id:
type: string
description: The operation identifier.
created:
type: string
description: The start date of the job.
status:
type: string
enum:
- scheduled
- in progress
- ready
- done
- error
description: |-
The status of the job.
**Possible values:**
- **scheduled:** The export process has not been started yet
- **in progress:** The export is currently being processed
- **ready:** The CSV file is ready for distribution
- **done:** The export finished without errors and the CSV file is created and distributed successfully
- **error:** An error occurred during the export process
**Note:** When using FTP and the host is unavailable, or the authentication failed, the export status still displays as ready. The process will try to reconnect to the FTP after one hour. If the export process still cannot connect (as in the status is *ready* for more than one hour), contact Emarsys support.
type:
type: string
enum:
- Responses
- Registrations
description: Indicates whether the export contains responses or registrations.
file_name:
type: string
description: |-
The name of the output CSV file.
**Note:** Changes from `null` when the status is *done*.
ftp_host:
type: string
description: The export settings to locate the file if the distribution method is FTP.
ftp_dir:
type: string
description: The export settings to locate the file if the distribution method is FTP.
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
'/v2/export/{exportId}/data':
get:
summary: Download Export Data
description: |-
Returns a CSV file once the export job is finished. You must set the distribution method to `local` when initiating an export job at the following endpoints:
- [Export Updated Contacts](/reference/openapi.json/paths/~1v2~1contact~1getchanges/post)
- [Export a Contact List](/reference/openapi.json/paths/~1v2~1email~1getcontacts/post)
- [Export a Segment](/reference/openapi.json/paths/~1v2~1export~1filter/post)
**Note:** It is recommended to use FTP or WebDAV to access exports. For configuration options, contact Emarsys support.
**Important:** This endpoint returns a file instead of JSON. The *Content-Type* of the response is `text/csv;charset=UTF-8`.
operationId: downloadExportData
produces:
- text/csv
parameters:
- name: exportId
in: path
description: 'The identifier of the export job initiated at the [Export Updated Contacts](/reference/openapi.json/paths/~1v2~1contact~1getchanges/post) endpoint.'
required: true
type: integer
- $ref: '#/parameters/trait:offset:offset'
- $ref: '#/parameters/trait:limit10M:limit'
schemes:
- https
responses:
default:
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
definitions:
default-response:
type: object
title: Default Response
description: |-
See the following documents for details on the error codes:
- [HTTP 200 errors](docs/response-codes/http-200-responses.md)
- [HTTP 400 errors](docs/response-codes/http-400-errors.md)
- [HTTP 401-429 errors](docs/response-codes/http-401-429-errors.md)
- [HTTP 500 errors](docs/response-codes/http-500-errors.md)
properties:
replyCode:
type: integer
description: 'The Emarsys response code. Successful requests return *0*; otherwise, see [errors](docs/response-codes/http-400-errors.md).'
default: 0
replyText:
type: string
description: Additional information on the status of the request.
data:
description: 'Contains the requested data, if applicable.'
oneOf:
- type: string
- type: integer
- x-nullable: true
- type: object
properties:
'':
type: object
x-examples:
- replyCode: 0
replyText: OK
data: {}
parameters:
'trait:filter:filter':
name: filter
in: query
type: string
'trait:limit10K:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
type: integer
default: 10000
maximum: 10000
minimum: 1
'trait:offset:offset':
name: offset
in: query
description: Specifies an offset for pagination. The offset of the first record is *0*.
type: integer
default: 0
'trait:limit1M:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
type: integer
default: 1000000
maximum: 1000000
minimum: 1
'trait:interval:start_date':
name: start_date
in: query
description: |-
Returns results from the specified date.
**Accepted formats:** YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD
type: string
'trait:interval:end_date':
name: end_date
in: query
description: |-
Returns results until the specified date.
**Accepted formats:** YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD
type: string
'trait:excludeEmptyResults:excludeempty':
name: excludeempty
in: query
description: |-
If `true`, contacts with a null or empty value in the specified field are not returned.
**Note:** Any value except for `true` is interpreted as false.
type: boolean
'trait:limit10M:limit':
name: limit
in: query
description: 'Specifies the maximum number of records to return. Please note that if this parameter is used, the response will be a JSON object. If the parameter is not used, the response will be a .csv file.'
type: integer
default: 10000000
maximum: 10000000
minimum: 1
'trait:limit1MRequired:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
required: true
type: integer
default: 1000000
maximum: 1000000
minimum: 1
'trait:limit1K:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
type: integer
default: 1000
maximum: 1000
minimum: 1
securityDefinitions:
X-WSSE:
type: apiKey
name: X-WSSE
in: header