SAP Emarsys Email API

openapi: 3.2.0
info:
  title: Emarsys Email API
  version: '1.0'
  description: 'Operations tagged Email across 7 of this provider''s published API definitions: emarsys-contact-and-email-data-openapi.yml, emarsys-email-campaign-lifecycle-openapi.yml, emarsys-email-campaigns-openapi.yml, emarsys-email-reporting-api-openapi.yml, emarsys-email-templates-openapi.yml, emarsys-sections-openapi.yml, emarsys-tracked-links-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emarsys.net/api
- url: https://api.emarsys.net
  description: Public API
tags:
- name: Email
paths:
  /v2/email/getcontacts:
    post:
      summary: Export a Contact List
      description: "Exports the specified fields of contacts from a contact list 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 `sftp` can be accessed via SFTP.\n- Exports flagged as `mail` are sent to the specified address when ready.\n\n**Implementation**\n\n You can implement this method as follows:\n- 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.\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](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) 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\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```\n\n> **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
      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 `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
      tags:
      - Email
    servers:
    - url: https://api.emarsys.net/api
  /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.\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 `sftp` can be accessed via SFTP.\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/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.\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/4qd2h7o1jnxmd-check-export-status) response. Failures are retried 5 times, with a one-minute wait between each try.\n\n**Notes**\n- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or SFTP access, contact Emarsys support.\n\n**Example**\n\n```csv\nuser_id;First Name;Last Name;E-Mail;Campaign title;Link title;Url;source\n287705659;user3;test_import;test1@emarsys.com;VisualCMS_2015_04_09_10_05_03;;www.emarsys.com;click\n287705659;user3;test_import;test1@emarsys.com;RSS_2015_04_09_10_05_03;;www.google.com.com;click\n287705659;user3;test_import;test1@emarsys.com;AC_recurring_2015_04_09_10_05_03;;;open\n```"
      operationId: exportResponses
      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
                  - 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
      tags:
      - Email
    servers:
    - url: https://api.emarsys.net/api
  /v2/email/{emailId}/preview:
    post:
      summary: Preview Email Campaign Contents
      description: Returns the HTML, plain text or mobile version of the email.
      operationId: previewEmailCampaignContents
      parameters:
      - name: emailId
        in: path
        description: The identifier of the email campaign.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '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:
                version:
                  type: string
                  enum:
                  - html
                  - text
                  - mobile
                  description: The content type of the response.
              required:
              - version
              x-examples:
              - version: html
      tags:
      - Email
    servers:
    - url: https://api.emarsys.net/api
  /v2/email/{emailId}/sendtestmail:
    post:
      summary: Send a Test Email
      description: 'Sends a test email to the specified recipient list, segment, or contact list. Recipient list types cannot be combined.


        **Note:** The number of recipients must be less than 50. Additional recipients are ignored.'
      operationId: sendTestEmail
      parameters:
      - name: emailId
        in: path
        description: The identifier of the email campaign.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '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:
                subject:
                  type: string
                recipientlist:
                  type: string
                  description: 'The list of recipient email addresses. Multiple values are allowed, separated by a comma without whitespace.


                    **Note:** Provide either a `recipientlist`, `filter_id` or `contactlist_id`. Do not combine.'
                filter_id:
                  type: integer
                  description: 'The identifier of the recipient segment. Multiple values are allowed, separated by a comma without whitespace.


                    **Note:** Provide either a `recipientlist`, `filter_id` or `contactlist_id`. Do not combine.'
                contactlist_id:
                  type: integer
                  description: 'The identifier of the recipient contact list. Multiple values are allowed, separated by a comma without whitespace.


                    **Note:** Provide either a `recipientlist`, `filter_id` or `contactlist_id`. Do not combine.'
              x-examples:
              - subject: superhero_party_invitation
                recipientlist: tony.stark@example.com; pepper.potts@example.com
      tags:
      - Email
    servers:
    - url: https://api.emarsys.net/api
  /v2/email/{emailId}/launch:
    post:
      summary: Launch an Email Campaign
      description: 'Initiates the launch of an existing email campaign. The actual launch takes place once the request is processed.


        This endpoint launches a campaign to receipients already in the Emarsys contact database. If the contacts are not imported yet (virtual contacts), use the Launch an Email Campaign to Virtual Contacts (Broadcast) endpoint instead.


        **Important:** This is an asynchronous operation, and may take a couple of minutes to complete. The request initiates a background job and returns an identifier. Poll the Get Email Campaign Data endpoint to track the launch progress. Check the `api_status` and `api_error` parameters for the current status.


        **Tip:** Configure the recipient segment or contact list using the Create an Email Campaign endpoint.


        **Note:** A successful launch request may result in a failed launch, if the campaign is not properly configured. For example, a missing email subject or unspecified recipient list prevents a launch.'
      operationId: launchEmailCampaign
      parameters:
      - name: emailId
        in: path
        description: The identifier of the email campaign.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '409':
          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:
                schedule:
                  type: string
                  description: 'If specified, the launch is scheduled for the provided date and time of the custumer''s default timezone.


                    **Accepted format:** YYYY-MM-DD HH-SS'
                  pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}
                timezone:
                  type: string
                  description: 'Applies the specified timezone to the launch time in the `schedule` parameter.


                    For the list of supported timezones, see [Timezones](docs/appendix/timezones.md).'
                features:
                  type: array
                  description: 'Specifies additional features for the email campaign.


                    Accepted values:

                    - `sto`: [Send Time Optimization](https://help.emarsys.com/hc/en-us/articles/115004470785-Send-Time-Optimization-Overview)


                    If any of the listed features are not available, contact Emarsys support.'
                  items:
                    type: string
                    enum:
                    - sto
              x-examples:
              - emailID: '1234567890'
                schedule: 2011-08-12 08:35
                timezone: America/New_York
                features:
                - sto
      tags:
      - Email
    servers:
    - url: https://api.emarsys.net/api
  /v2/email/{emailId}/broadcast:
    post:
      summary: Launch an Email Campaign to Virtual Contacts (Broadcast)
      description: 'Launches an email campaign to contacts who are not in the Emarsys contact database (virtual contacts).


        **Important:** Because no personalization data is available for virtual contacts, the email address and all personalization data must be provided in the payload of the request.


        **Note:** You can launch a campaign to a single contact on this endpoint at a time.'
      operationId: launchEmailCampaignVirtualContacts
      parameters:
      - name: emailId
        in: path
        description: The identifier of the campaign.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  replyCode:
                    type: integer
                  replyText:
                    type: string
                  data:
                    type: string
        '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:
                email:
                  type: string
                  description: The email address of the contact not in the Emarsys database.
                  format: email
                data:
                  type: object
                  description: The personalization data for the campaign.
                  properties:
                    global:
                      type: object
                      description: A functional object for *Broadcast* type emails. Include the payload under this object.
              required:
              - email
              x-examples:
              - email: virtual@contact.com
                data:
                  global:
                    orderId: '123456789'
                    orderDate: '2019-08-07'
                    subject: Test payload
      tags:
      - Email
    servers:
    - url: https://api.emarsys.net/api
  /v2/email/{emailId}/stop:
    post:
      summary: Stop an Email Campaign
      description: 'Stops an exiting email campaign, depending on its type.

        - Deactivates **triggered email campaigns**. Until the campaign is reactivated, any associated events are ignored and the campaign is not launched. For details and on-event mail stream statuses, see [Triggered Email User Guide](https://help.emarsys.com/hc/en-us/articles/115004461489-Triggered-Email-end-user-guide#the-mail-streams-list).

        - Aborts or unschedules **transactional campaigns**. Aborted campaigns cannot be rescheduled, while unscheduled ones revert to *In Design* status.


        **Note:** Already launched campaigns used in an Automation Center program cannot be stopped.'
      operationId: stopEmailCampaign
      parameters:
      - name: emailId
        in: path
        description: 'The identifier of the email campaign.

          '
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Email
    servers:
    - url: https://api.emarsys.net/api
  /v2/email/getdeliverystatus:
    post:
      summary: Query Delivery Status
      description: Returns the delivery status of an email campaign.
      operationId: queryDeliveryStatus
      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:
                      resultSet:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              description: The identifier of the email campaign.
                            user_id:
                              type: integer
                              description: The user identifier.
                            bounce_reason:
                              type: string
                              description: The bounce type. For details, see [Bounce Management](https://help.emarsys.com/hc/en-us/articles/115004556729-Bounce-Management#bounce-types).
                            status:
                              type: string
                              description: The status of the campaign. For details, see [Email status and error codes](docs/personalization/email-status-and-error-codes.md).
                            mail_type:
                              type: string
                              enum:
                              - html
                              - text
                              description: The type of the email.
                      lastId:
                        type: integer
                        description: The last returned identifier.
        '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:
                emailId:
                  type: integer
                  description: The identifier of the email campaign.
                launchId:
                  type: integer
                  description: 'The identifier of the launch.


                    **Note:** This parameter is mandatory if the campaign has multiple launches.'
                lastId:
                  type: integer
                  description: '`lastid` helps you with the pagination of the results. You get next page of data that comes *after* `lastid` in the resultset. The piece of data `lastid` refers to i

# --- truncated at 32 KB (145 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emarsys/refs/heads/main/openapi/emarsys-email-api-openapi.yml