openapi: 3.0.2
info:
  title: Webexpress Subscriber and Opt-Out List Import
  version: '1.0'
  description: >
    The automated import of subscriber and opt-out lists is simplified by using
    an

    interface to which different CRM systems can be linked. The parameters that

    must be configured in order to use this interface are detailed below.


    The upload is executed via HTTPS using POST in multipart/form data encoding,

    with the transfer of key value pairs. Non-secure HTTP connections are
    rejected.


    ## General Rules

    * Users can always upload lists for themselves. A user can upload lists for

    other users in the same company if they have an identical or lower security

    level (e.g., Customer Admin for customer staff).

    * Individual parts of a list cannot be modified, e.g., by adding or deleting

    information.

    * If a line contains an invalid value at any point, no part of it can be

    imported, and the corresponding error message appears.

    * If a column type is detected more than once, the upload is canceled

    (e.g., two fax columns).

    * If a login is valid, the error messages appear in the language of the

    uploading user, otherwise they will be in English.

    * Multiple files must be uploaded separately.

    * Invalid data cause the upload to be cancelled and an error message
    appears.

    * If any required data is missing, the upload is cancelled and an error

    message appears.

    * Recipient numbers must always be entered with their country code. The

    country code usually must have zero in front of it.

    * Recipient numbers without a country code are rejected.

    * Recipient numbers without a country code have __dlu_defaultcountrycode__

    added to them.

    * All of the list columns are always imported. Columns that do not contain

    "ref", "email", "fax" or "sms" become personalized columns.

    * Uploads cannot have a blank list name.

    * The Reference column is optional.

    * If the maximum number of columns is exceeded the upload is cancelled

    (there can only be a maximum of 4 media columns and 13 personalization

    columns). Column names cannot exceed 64 characters.


    ## Defining Column Types

    When uploading a new list, Webexpress can automatically recognize the

    columns containg the data types

    refernce, email address, fax number and mobile number. There are two

    methods that Webexpress

    uses to recognize the special columns.

    * The column title matches the list of defined names

    * The column title is tagged with column type


    In order for the recognition to

    * column headings must be specified

    * __dlu_firstrowcolumnnames__ mus be set to on

    ## Updating Existing lists

    In order to update an existing list the following criteria must be
    fulfilled.

    * If the __dlu_firstrowcolumnnames__ option is used, the column names must

    be identical to the existing list. If this is not the case, the upload is

    cancelled and an error message appears.

    * The number of columns must be identical to the number in the existing
    list.

    * The column types are always taken from the existing list.

    * If __dlu_listcomment__ is entered, the existing comments are also replaced

    (otherwise, they are not).
servers:
  - url: https://webexpress.retarus.com/PicoPortal/autoLogin
paths:
  /listImport:
    post:
      security:
        - basicAuth: []
      tags:
        - Lists
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - dlu_listname
                - dlu_listcomment
                - dlu_type
                - dlu_defaultcountrycode
                - dlu_firstrowcolumnnames
                - dlu_charset
                - dlu_file
              properties:
                dlu_listname:
                  description: >-
                    The unique name of the list. If the name matches an existing
                    list, the list will be replaced, otherwise a new list ist
                    created with that name.
                  type: string
                  example: CustomersFrance
                dlu_listcomment:
                  description: Comments to describe the list.
                  type: string
                  example: All customers in France
                dlu_type:
                  $ref: '#/components/schemas/ListType'
                dlu_file:
                  description: The content of the the csv file (list).
                  type: string
                  format: binary
                dlu_defaultcountrycode:
                  $ref: '#/components/schemas/CountryCode'
                dlu_firstrowcolumnnames:
                  $ref: '#/components/schemas/FirstRowColumnNames'
                dlu_charset:
                  $ref: '#/components/schemas/CharacterSet'
                dlu_targetuser:
                  type: string
                  description: >-
                    The Webexpress user this list should be assigned to -
                    relevant in combination with the dlu_visibility value.
                  nullable: false
                  example: john.smith@acme.com
                dlu_visibility:
                  $ref: '#/components/schemas/ListVisibility'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
              examples:
                NewList:
                  summary: New list
                  value: |
                    Transmitted data::
                      User Name (j_username):                 john.smith@acme.com
                      List Name (dlu_listname):               CustomersFrance
                      List Comment (dlu_listcomment):         All customers in France
                      Default Country Code  (dlu_defaultcountrycode): +33
                      Column Names (dlu_firstrowcolumnnames): on
                      Charset (dlu_charset):                  UTF-8
                      List Type (dlu_type):                   distributionlist
                      File (dlu_file):                        list.csv [69 Bytes]

                    Detected column types:
                      1: ref [Reference]
                      2: name [Field]
                      3: mobile [SMS]

                    The list has been created.

                    -> The list has been successfully imported.
                UpdateList:
                  summary: Update list
                  value: |
                    Transmitted data::
                      User Name (j_username):                 john.smith@acme.com
                      List Name (dlu_listname):               CustomersFrance
                      List Comment (dlu_listcomment):         All customers in France
                      Default Country Code  (dlu_defaultcountrycode): +33
                      Column Names (dlu_firstrowcolumnnames): on
                      Charset (dlu_charset):                  UTF-8
                      List Type (dlu_type):                   distributionlist
                      File (dlu_file):                        testdistributionlist.csv [61 Bytes]

                    Detected column types:
                      1: ref [Reference]
                      2: name [Field]
                      3: fax [Fax]

                    The list has been replaced.

                    -> The list has been successfully imported.
        '403':
          description: forbidden
        '500':
          description: >-
            internal server error - invalid request. missing required property
            or the file contents comes before the credentials.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    ListType:
      description: The list type - either a distribution list or an opt-out list.
      type: string
      default: distributionlist
      enum:
        - distributionlist
        - blacklist
    FirstRowColumnNames:
      description: >-
        Flag specifying whether the first row of csv file contains the column
        names - ie the first row contains the headers.
      type: string
      default: 'on'
      enum:
        - 'on'
        - 'off'
    CountryCode:
      description: >-
        The country code to use to auto-complete fax and mobile phone numbers
        that do not include the country code.
      type: string
      pattern: ^\+[1-9]{1}[0-9]{0,2}$
      example: '+33'
    CharacterSet:
      description: The character set with which the csv list file is encoded.
      type: string
      default: UTF-8
      enum:
        - UTF-8
        - ISO-8859-1
    ListVisibility:
      description: >-
        Whether the list should be visible to all users in the Webexpress tenant
        or only a single user
      type: string
      default: company
      enum:
        - company
        - user
