SAP Emarsys Export API

openapi: 3.2.0
info:
  title: Emarsys Core API - Contact and email data endpoint batch Export API
  description: In this batch you may find endpoints related to contact and email data.
  version: v2
servers:
- url: https://api.emarsys.net/api
tags:
- name: Export
paths:
  /v2/export/filter:
    post:
      summary: Export a Segment
      description: "Exports the specified fields of contacts from a segment as a CSV file.\n\n**Important:** \n\nThe results are saved as a CSV file that you can access in multiple ways.\n- Exports flagged as `local` are stored on the Emarsys server that you can download via WebDAV or an API call.\n- Exports flagged as `ftp` can be accessed via FTP.\n- Exports flagged as `sftp` can be accessed via SFTP.\n- Exports flagged as `mail` are sent to the specified address when ready.\n\n**Implementation**\n\nou can implement this method as follows:\n- 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.\n- 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.\n\n**Notes**\n- As we are using a proxy for FTP traffic, it is not necessary to whitelist any IPs on our side.\n- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or (S)FTP access, contact Emarsys support.\n\n**Example**\n\nAn example contact list export including first name, last name, email address and opt-in status results in the following CSV:\n```csv\nFirst Name;Last Name;E-mail;Opt-in\nFname_1;Lname_1;testuser@example.com;True\nFname_2;Lname_2;testuser@example.com;True\nFname_3;Lname_3;testuser@example.com;True\nFname_4;Lname_4;testuser@example.com;True\n```"
      operationId: exportSegment
      responses:
        '200':
          description: ''
          content:
            application/json:
              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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            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
      tags:
      - Export
  /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
      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
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Export
  /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
      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
        schema:
          type: integer
      - $ref: '#/components/parameters/trait_offset_offset'
      - $ref: '#/components/parameters/trait_limit10M_limit'
      responses:
        default:
          description: ''
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Export
components:
  parameters:
    trait_offset_offset:
      name: offset
      in: query
      description: Specifies an offset for pagination. The offset of the first record is *0*.
      schema:
        type: integer
        default: 0
    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.
      schema:
        type: integer
        default: 10000000
        maximum: 10000000
        minimum: 1
  schemas:
    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
          - {}
          - type: object
            properties:
              ? ''
              : type: object
      x-examples:
      - replyCode: 0
        replyText: OK
        data: {}
  securitySchemes:
    X-WSSE:
      type: apiKey
      name: X-WSSE
      in: header