Topica Web Services

Overview

Topica offers SOAP-based access to certain functions of the Topica system. SOAP provides a method of access via HTTP by sending TopicaAction messages to the Topica web server.

Table of contents

Subscriber Export
Subscriber Import
Subscriber Unsubscribe
Sample Code

Current Features

The schema for Topica's web services is located
here (services.xsd)

All Topica messages are comprised of a topicaAction enclosed within the body of a SOAP message. The topicaAction body includes user authentication and information about the list.

For example:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
        <topicaAction username="your_login@your_domain.com" password="your_password"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:SchemaLocation="http://www.topica.com/services/services.xsd"
                xmlns="http://www.topica.com/Dispatcher/" >
                <someTopicaAction/>
        </topicaAction>
  </soap:Body>
</soap:Envelope>
Each request must include a valid username and password. A successful request will return success. If an error is encountered, it will be returned to the user.

Requests are submitted to http://www.topica.com/api/Dispatcher using SOAP (HTTP Post).

 

Subscriber Export

Subscriber Export takes the form of the following. Values which must be changed are displayed in red.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
        <topicaAction username="your_login@your_domain.com" password="your_password"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:SchemaLocation="http://www.topica.com/services/services.xsd"
                xmlns="http://www.topica.com/Dispatcher/" >
                <subscriberExport
                        list="your_list@app.topica.com"
                        column-delimiter=","
                        value-delimiter=";"
                        export-type="active"
                        from-date="2001-01-01"
                        to-date="2004-01-01"
                        email-to="your_email@your_domain.com"
                        upload-url="ftp://user:pass@your_domain.com/home/joe/your-file.zip"/>
        </topicaAction>
  </soap:Body>
</soap:Envelope>
The results of the action will be mailed to the address specified in the email-to field. Configuration details include:
list
A valid list name must be provided.
from-date / to-date
Beginning and end dates. The format is YYYY-MM-DD with an optional time THH:SS:ss such as 2001-01-02T14:30:00. The time zone is the Pacific Timezone (PST / PDT / Los Angeles) time.
export-type
Allows subscribers to be selected based on their status. If disabled or unsubscribed is selected, only those subscribers whose status has changed in the selected date range will be exported.
Valid options are [active | disabled | unsubscribed | all].
upload-url
If an upload-url is provided, the service will ftp the results to that location rather than mailing them to the email-to address. The email-to address will still receive a status email. Please note that the file will be placed in the path provided as a zip file.

 

Subscriber Import

Subscriber Import is analagous to the browser-based imports. Each field in the record is assigned to a database field, and flags are set for handling the import. This feature allows for a flexible configuration options.

Also, it is possible to import subscribers via inline and via a web url. For large amounts of subscribers, placing the subscriber list on a web-accessible url is recommended.

Imports are of the following general form:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
        <topicaAction username="your_login@your_domain.com" password="your_password"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:SchemaLocation="http://www.topica.com/services/services.xsd"
                xmlns="http://www.topica.com/Dispatcher/" >
                <subscriberImport
                      list="your_list@app.topica.com"
                      column-delimiter=","
                      value-delimiter=";"
                      duplicate="replace-existing"
                      first-row="data"
                      send-confirmations="false"
                      email-to="your_email@your_domain.com">
                      <mapping>
                          <column order="1" field="Email Address"  create-if-new="false"/>
                          <column order="2" field="Favorite Color" create-if-new="true"  data-type="multi">
                            <category-values convert-case="true" create-if-new="true">
                                  <map from="y" to="Yellow"/>
                                  <map from="yellow" to="Yellow"/>
                                  <map from="b" to="Black"/>
                            </category-values>
                          </column>
                          <column order="3" field="Address 1" create-if-new="true" data-type="text"/>
                          <column order="4" field="Address 2" create-if-new="true" data-type="text"/>
                          <column order="5" field="City" create-if-new="true" data-type="text"/>
                          <column order="6" field="State or Province" create-if-new="false" data-type="category"/>
                      </mapping>
                      <data source="url">http://www.topica.com/services/sample_import.txt</data>
                </subscriberImport>
        </topicaAction>
  </soap:Body>
</soap:Envelope>
In the example above, the subscriber list is downloaded from http://www.topica.com/services/sample_import.txt. The order of the fields is specified, and, in the case of "Favorite Color," the values are mapped onto other values (ie, "y" becomes "Yellow").

Below are explanations for some of the important features of the configuration:

firstrow
Can be 'data' or 'header'
duplicate
Defines action when email address already found. Maps to existing import choices.
Acceptable values: [ complete-overwrite | replace-existing | preserve-existing | reject-duplicates ]

All of the import methods will import the entire subscriber record if the subscriber is new, however, if the subscriber already exists, the behavior differs as follows:

complete-overwrite - drops the subscriber and replace with the new record.
replace-existing - update the subscriber with the new data.
preserve-existing - keep subscriber data, only add to the record, do not overwrite.
reject-duplicates - This is the default. Do not import the subscriber if the subscriber already exists.

send-confirmations
Determines whether to send a confirmation to the subscriber (confirmed optin) or import them as active (single optin).
Acceptable values: [ true | false | force-restricted-pending | confirm-restricted-only ]

true - Confirm all subscribers.
false - Confirm no subscribers, if possible, otherwise, default to "force-restricted-pending."
force-restricted-pending - Do not confirm subscribers. Domains that require confirmation will be set to pending.
confirm-restricted-only - Only send confirmations to domains that require them.

list
List can be either email address or LIST_ID.
mapping
Mapping contains list of column mapping definitions. Order attribute defines which column it is, and starts at 1 (for readability).
field
Field must match case insensitively name of an existing DB field, or a system field name as defined in @T3::List::Demographics::SYSTEM_FIELDS. If field is blank, this field is skipped. Note that it will still require a row in IECOLMAPPINGS table.
create-if-new
Specifies action if the field name was not found. If true, field is created, if false and field was not found, the import should be aborted.
data-type
Required if create-if-new is true. Defines the data type for new field.
category-values
This item defines configuration of a category field.
create-if-new
If set to true, all new category fields will be automatically created. Otherwise any new values are simply ignored. Note the difference compared to the column's create-if-new.
convert-case
This is something that UI already does today, but would be of great benefit to have in offline imports too. Basically, it upper cases the first letter of each word in the category value. So ``downHill SkiiIng'' becomes ``Downhill Skiing''. It basically makes category values look much nicer. Note that this only applies to creating new category values. If true, all new values should be created with the case converted as above.
map
This item optionally indicates mapping for some values in the data file. If the value being mapped to does not exist, it should be created as new (effectively substituting old value).
data
This is what defines the actual import file. Source of data depends on ``source'' attribute.
source
"inline" means that data is part of the XML file. "uri" means that data should be loaded via an HTTP fetch from a given URI (which could be http://, ftp://, etc)

 

Subscriber Unsubscribe

Subscriber Unsubscribe is a basic message structure. It takes a list of subscribers which can be included inline, or downloaded from a URL, and unsubscribes them, mailing the results back to the email specified. Values which must be changed are displayed in red.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
        <topicaAction username="your_login@your_domain.com" password="your_password"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:SchemaLocation="http://www.topica.com/services/services.xsd"
                xmlns="http://www.topica.com/Dispatcher/" >
                <subscriberUnsubscribe
                        list="your_list@app.topica.com"
                        email-to="your_email@your_domain.com">
                      <data source="url">http://www.topica.com/services/sample_unsubscribe.txt</data>
                </subscriberUnsubscribe>
        </topicaAction>
  </soap:Body>
</soap:Envelope>
The results of the action will be mailed to the address specified in the email-to field. Configuration details include:
data
This is list of subscribers. The source of data depends on ``source'' attribute and can be inline or loaded from a uri.
source
Acceptable values: [ inline | uri ]
inline means that data is included in the <data/> element and is specified as a list of subscribers separated by newlines.
uri means that data should be loaded via an HTTP fetch from a given URI (which could be http://, ftp://, etc)

 

Sample Code

The following are perl scripts demonstrating simple requests.
Subscriber Export
Subscriber Import