(Customer Profile Interface)
General DescriptionThe CPI serves the purpose of transferring personal data to the XQueue database. The usual processes are: – Subscription – Unsubscribing – Profile Modification Communication and data exchange is done using HTTP POST requests. Depending on the account configuration, further actions triggered by XQueue are possible. These are: – Sending a confirm email – Sending a double-optin mail – Sending various notifier emails to one or more permanently defined email addresses
Communication and Data SecurityThe XQueue CPI is addressable for communication with external data processing systems via the HTTPS protocol which enables encoded data exchange. In addition, access to the XQueue CPI is protected by an account-independent authentication procedure. Each transaction made via the XQueue CPI is logged.
POST ParametersFor each transfer, the following parameters are required for authentication purposes: ent => account ID usr => login pwd => password The next parameter defines the transfer type: subscription or unsubscribing. Without this parameter a transfer is not possible. p_status => value: A = subscription | value: U = unsubscribe The last mandatory field is the email address. It must not be empty and will be checked for syntax errors. If the transferred email address is invalid, transfer will be canceled. email => email address The following parameters are optional. They can be used to enrich the personal profile stored in our system with data. salut => salutation (alphanumeric/ max. 100 characters) You can alternatively transfer the values 1, 2 or 3. In such cases the CPI will convert the transferred values as follows: 1 => Sehr geehrter Herr 2 => Sehr geehrte Frau 3 => Sehr geehrte Damen und Herren This automatic conversion can be deactivated by the account manager in charge. title => title (alphanumeric/ max. 255 characters) fname => first name (alphanumeric/ max. 50 characters) lname => last name (alphanumeric/ max. 50 characters) format => newsletter format value: H = HTML | value: T = text | value: M = multipart If this parameter is not transferred it will automatically be set to M. The format controls the newsletter format as it will be used for dispatch of the newsletter to this person. Any transferred value other than H, T or M will result in this person not receiving any email from the XQueue system! street => street name (alphanumeric/ max. 140 characters) city => city (alphanumeric/ max. 60 characters) zip => ZIP code (alphanumeric/ max. 20 characters) country => country (alphanumeric/ max. 255 characters) company => company name (alphanumeric/ max 255 characters) geb => date of birth (format YYYY-MM-DD) You can optionally transfer following parameters: geburtsjahr geburtsmonat geburtstag These will automatically be converted into the correct format. ring transfer, the CPI uses the email address to check whether such a data record already exists. If yes, no new record will be created but the existing one will be updated with the new parameters (profile change). In case the email address should not be used as primary key, the parameter ext_id can be used instead. When this parameter is transferred, only this ID will be used for data record matching. If no match is found, a new record will be created even if the email address already exists! ext_id => external ID (alphanumeric/ max. 20 characters) The parameter to use as primary key should be defined in advance and under no circumstances be changed from transfer to transfer, since this will lead to unwanted address dupes. Following parameters control the return/ behavior of the CPI after transferring. There are two primary application options for integration of the CPI. A: HTML form target page (POST action) B: POST Requests performed in the background For designated use of A you can transfer the following parameters: redirect_check => URL for redirect in case an invalid email address has been entered. If this parameter is not transferred, this will result in automatic forwarding to redirect_error. redirect_ok => URL for redirect when no errors have occurred redirect_error => URL for redirect if errors have occurred update_ok => URL for redirect upon successful data record update For designated use of B you can transfer the following parameters: ret => manages formatting of the return value. Possible values are: cd => code. A status code is transferred (0,1,2). 0 = OK, 1 = error, 2 = update xml => return will be performed in XML format html => return will be performed in HTML format update_ok => value: on If this parameter is not transferred, no distinction will be made between new data record and update. An OK will be returned in both cases. This parameter returns various status codes.
POST Special ParametersFollowing please find a list of special parameters enabling you to dynamically expand account configuration or perform transfer specific actions email_neu => new email address. Only works in conjunction with the parameter email. Both parameters must be transferred and have different values. Thus you can allocate a new email address to an existing data record. charset => charset encoding for the transferred parameters. For instance UTF-8. When data are transferred to the CPI UTF-8 encoded this parameter must be transferred. Otherwise the data cannot be displayed properly in the XQueue system. The default charset setting is ISO-8859-1 and thus normally does not need to be mentioned explicitly. ono => value: 1 This parameter suppresses the configuration done in the account regarding confirmed or double-optin. The transferred data records will be actively available in the account instantly and will not receive any confirmed or double-optin email. Please note that, according to German law, subscriptions without a double-optin process are not permitted. gosin => value: 1 Configuration done in the account can be bypassed using this parameter. It must be transferred as ono (value 1) and enforces sending a confirmed e-mail, even when double-optin had been activated on account level. no_update => value: 1 This parameter blocks updating of master data for an already existing data record. Only status and CHANGEDATE will be updated. d_optin_altbody => value: 1 Activates the alternative text for double-optin emails provided in the account. d_optin_altsubject => value: 1 Activates the alternative subject for double-optin emails provided in the account. lang => value: alphanumeric Double-optin configurations can be stored as so-called LANG. This enables you to store multiple double-optin text versions in one account. This parameter activates the desired language pack. no_welcomemail => value: 1 Suppresses sending a welcome mail, even if it had been activated on account level. follow_mail => value: 1 Activates dispatch of a follow mail. For use of the follow mail feature, please revert to your account manager. follom_mail_eid => value: integer Can only be used in conjunction with follow_mail. Contains the ID of a newsletter which is used as template for the followmail.
POST Profile ParametersBesides master data, you can also transfer so-called contact fields. These enhance the master data records, adding client specific information for each individual data record. Examples for contact fields are: age, shoe size, telephone number etc… You can create as many own contact fields as you like, each of them can contain up to 255 alphanumeric characters. Each contact field has its own, unique ID. These IDs are required for the data transfer (they can be obtained from your account manager). The parameter name will always begin with a „pp“ followed by the ID. e.g. pp1000 pp1001 pp1002 … A further parameter is required, informing the CPI about transfer and type of contact fields. The parameter name is „options“, the value is a comma-separated ID list. e.g. options => 1000,1001,10002 Here only the IDs are listed, without the appendage „pp“. ]]>