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.<br><br>**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.
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emarsys/refs/heads/main/openapi/emarsys-contact-and-email-data-openapi.yml