Topica Web Services

Overview

Table of contents

Subscriber Export

Subscriber Import

Subscriber Unsubscribe

Sample Code

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>

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

Subscriber Export

<?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>

Subscriber Import

<?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="complete-overwrite"
                      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>

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

<?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>

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

Subscriber Export

Subscriber Import