exacttarget api guide.117 - amazon web...

ExactTarget API Guide

Last Updated: May 11, 2007

Confidential and Proprietary. This document and all information contained herein are the exclusive property of ExactTarget, Inc. The recipient of this document has been granted no rights to duplicate (in any medium) or distribute this document.

© 2005–2006 ExactTarget, Inc. All rights reserved. All products referenced herein are registered trademarks or trademarks of their

respective holders.

iii

Table Of Contents

1. Introduction to ExactTarget Developer Integration Help.................................................................. 1

About the ExactTarget API......................................................................................................................... 2

Business Scenarios...................................................................................................................................... 3

Manage Data............................................................................................................................. 3

Remote Sending ....................................................................................................................... 4

Track Subscriber Events ........................................................................................................... 4

2. ExactTarget API Guide ......................................................................................................................... 5

Introduction to ExactTarget API Guide...................................................................................................... 6

Important Information about Requirements and Security........................................................................... 7

API Support and Updates ......................................................................................................... 7

Serial Calls and Retries............................................................................................................. 7

Security ..................................................................................................................................... 7

Best Practices ........................................................................................................................... 8

How to Construct Your Calling Application ............................................................................................ 10

Base XML Format ................................................................................................................... 10

HTTP Construction.................................................................................................................. 11

Results .................................................................................................................................... 11

Direct Link to ExactTarget via Querystring ............................................................................. 12

Conventions and Other Information ......................................................................................................... 14

Code Sample Format .............................................................................................................. 14

Identifiers (ID Codes) .............................................................................................................. 14

Profile and Preference Attributes ............................................................................................ 16

Supported ASCII Characters .................................................................................................. 16

Checking the Status of the ExactTarget API ............................................................................................ 17

Method .................................................................................................................................... 17

Results .................................................................................................................................... 17

Subscriber Management ........................................................................................................................... 18

Introduction to Subscriber Management ................................................................................. 18

Subscriber Add........................................................................................................................ 18

Subscriber Edit (Update)......................................................................................................... 20

Subscriber Retrieve................................................................................................................. 23

Subscriber Delete.................................................................................................................... 26

Subscriber Master Unsub (Master Unsubscribe List) ............................................................. 28

Master Unsub Retrieve ........................................................................................................... 30

FTAF (Forward to a Friend) Retrieve...................................................................................... 31

List Management ...................................................................................................................................... 35

Introduction to List Management............................................................................................. 35

Attributes (Account Info) Retrieve ........................................................................................... 35

List Add ................................................................................................................................... 37

List Edit (Rename) .................................................................................................................. 38

List Retrieve ............................................................................................................................ 39

List Import (Upload Trigger) .................................................................................................... 42

List Import Status Check ......................................................................................................... 47

List Retrieve Subscribers ........................................................................................................ 48


iv

List Delete ............................................................................................................................... 50

List Retrieve Groups (All Groups) ........................................................................................... 52

List Refresh Group .................................................................................................................. 53

Group Refresh Status Check (Batch Inquire) ......................................................................... 55

Email Management ................................................................................................................................... 57

Introduction to Email Management ......................................................................................... 57

Email Retrieve All (Email IDs)................................................................................................. 57

Email Add HTML Paste........................................................................................................... 59

Email Add Text Version........................................................................................................... 62

Email Retrieve Body................................................................................................................ 64

Jobs (Remote Triggers)............................................................................................................................. 70

Introduction to Jobs (Remote Sending) .................................................................................. 70

Job Send (Mass Email) ........................................................................................................... 70

Job Send Single ...................................................................................................................... 72

Tracking (Event Data Requests) ............................................................................................................... 75

Introduction to Tracking (Event Data Requests) ..................................................................... 75

Tracking Retrieve Job IDs....................................................................................................... 75

Tracking Retrieve Summary ................................................................................................... 77

Tracking Retrieve (Bulk Export) .............................................................................................. 79

Tracking Retrieve Single Subscriber....................................................................................... 85

Tracking Retrieve Unsubscribes ............................................................................................. 87

Image Management .................................................................................................................................. 89

Introduction to Image Management ........................................................................................ 89

Image Import (Upload Trigger)................................................................................................ 89

3. API Application Code Samples .......................................................................................................... 93

Introduction to Application Code Samples............................................................................................... 94

Visual Basic Example............................................................................................................................... 95

ASP Example: Add List............................................................................................................................ 98

ASP Example: Retrieve Tracking Data .................................................................................................. 101

ASP Example: Add HTML Paste Email................................................................................................. 104

4. API Error Codes.................................................................................................................................111

Introduction to Error Codes .................................................................................................................... 112

Error Code Numbers and Descriptions ................................................................................................... 113

0 through 9 ............................................................................................................................ 113

10 through 19 ........................................................................................................................ 114

20 through 29 ........................................................................................................................ 115

30 through 39 ........................................................................................................................ 116

40 through 49 ........................................................................................................................ 117

50 through 59 ........................................................................................................................ 118

60 through 69 ........................................................................................................................ 118

70 through 79 ........................................................................................................................ 119

80 through 89 ........................................................................................................................ 120

90 through 99 ........................................................................................................................ 121

100 through 109 .................................................................................................................... 121

110 and Higher...................................................................................................................... 122

Table Of Contents

v

5. ExactTarget Resources...................................................................................................................... 125

Support.................................................................................................................................................... 126

ExactTarget Developer Community ...................................................................................... 126

System Requirements........................................................................................................... 126

Online Support Form............................................................................................................. 126

About ExactTarget Support................................................................................................... 126

Weekly Site Maintenance...................................................................................................... 126

Training .................................................................................................................................................. 128

Access and Registration Instructions.................................................................................... 128

ExactTarget Quickstart.......................................................................................................... 129

Fundamentals & Features of Email Creation ........................................................................ 129

Fundamentals & Features of Subscribers and Tracking....................................................... 129

Fundamentals & Features of HTML Email and Template Creation...................................... 129

Deliverability Best Practices in Email Marketing................................................................... 130

Feedback on ExactTarget Documentation .............................................................................................. 131

1

Introduction to ExactTarget Developer

Integration Help �� about the exacttarget api �� business scenarios

ExactTarget has designed and built a multi-tier architecture which delineates user interface, business logic

and data access. As a result, the business logic objects can be called from processes other than our user

interface. This allows the same program code to be run, regardless of whether it is executed by a user

navigating the site or a remote process triggers from a client application.

This documentation is designed to help you integrate with the ExactTarget API, as well as to integrate your

ExactTarget emails with your external datamart, customer relationship management system (CRM), or

content management system.

If you require additional assistance, contact ExactTarget at 866-558-9823 (toll free) or 317-275-5483

(local) to speak to a Software Support Specialist. Be sure to have your member ID handy (you can find

your member ID, also called your account ID, in the upper-right corner of your ExactTarget application

window).

Tip: You can download a PDF containing complete details of changes made in the most recent release of

the ExactTarget API by clicking here:

http://memberlandingpages.com/help/ReleaseNotes/ExactTarget_API_Latest_Release_Notes.pdf


2

About the ExactTarget API Many organizations face the challenge of merging their disparate data sources in order to manage their

marketing and CRM needs. Integrating customer data from your CRM package or contact management

system with your email marketing software is critical to creating a personalized dialogue with your

customers and prospects.

ExactTarget's design features a layered, modular application that allows us to integrate with external data

sources easily. The API allows for connections to external systems via commonly used protocols. However,

given that the number of methods and formats for communication is nearly infinite, we have a seasoned

development staff with more than 20 years' experience in systems integration that can assist our clients in

custom integration efforts.

Introduction to ExactTarget Developer Integration Help

3

Business Scenarios A variety of business scenarios must be supported through data and systems integration. The majority of

our clients’ needs revolve around data integration with one of a variety of systems that are designed to

support customer communication. These systems commonly include the following:

� CRM packages, such as Applix, Baan, Onyx, and Siebel.

� Marketing datamarts, databases, and campaign management systems, such as SAS.

� Content management systems.

� Portal management software.

We have not designed solutions for any specific product because even two clients in similar industries,

using similar CRM packages, may have vastly different requirements around their data integration needs.

Rather, we have designed interfaces that allow you to design a solution that best fits your needs.

The types of integration with these systems cover a variety of different business scenarios. However, there

are common themes to the needs. They fall into general categories.

� Manage data: Load messages, content, and subscribers into the ExactTarget system.

� Remote sending: Generate communications to your constituents (subscribers) both manually and

through remote, automated processes.

� Receive and record subscriber tracking events: Track and measure, individually and in

aggregate, the resulting activity that occurs from each communication. The activity can be as

simple as an email open or can include the steps that follow a click-through and ultimately result

in a sale. This information is accessible within the ExactTarget application, but you may want to

receive notification and store the information within your own systems.

Manage Data

The majority of our clients store vast amounts of information about their customers in CRM packages.

Further, they store vast amounts of information about their products and services in content management

systems. We provide many methods to get this information into the ExactTarget system through our web-

based interface.

For instance, using the interfaces we provide, you can build email messages, load subscriber information,

and upload custom content to be delivered to those subscribers in the ExactTarget application.

Many clients need a more automated system to perform these tasks. Our API provides a means to transfer

large lists of subscribers to the ExactTarget system and then subsequently manage those lists automatically.

You can also upload updates to your customer information into ExactTarget so that this updated

information can be used to customize and target your communications.

Once the customer information is available, messages can be built which contain custom content for those

subscribers. The custom content can be easily built and managed within the ExactTarget content libraries

through the web-based interfaces. If you use content management systems, you can choose to have your

information remain under your CMS's management and be dynamically included in an email at the time the

email is sent.


4

Remote Sending

ExactTarget provides secure mechanisms for our clients to send emails remotely and perform other

activities within our system. Virtually any activity that can be performed through the web-based interface

can be performed through our API.

One common client scenario occurs when a CRM system identifies a list of customers that should be

notified of an upcoming product launch. The system should generate the list and automatically transfer and

load it into the ExactTarget system using the API so that no special user tasks are required.

A second scenario can occur when a client’s campaign management software decides to trigger a

communication. For instance, you may want to send an email to one or several of your customers based on

an event that occurs within the campaign management system. Here, triggering the email communication

should be automatic and not require users to move between systems.

Track Subscriber Events

You may want to record and store these individual tracking events at the subscriber level. For instance, it

would be useful for users of the CRM system to know when a particular customer received an email and

whether the customer clicked on a link related to a certain service or product that you sell.

This information, which is recorded and stored within the ExactTarget Reporting Data Warehouse, can be

transferred, in aggregate or individually, into your CRM system using tracking API calls.

5



6

Introduction to ExactTarget API Guide

This section of the documentation details the API calls available to you.

Refer to Conventions and Other Information for an understanding of the code samples shown in these

topics.

For information about using these code samples in your application, see How to Construct Your Calling

Application.

See also Important Information about Requirements and Security.


7

Important Information about Requirements and Security

�� api support and updates �� serial calls and retries �� security �� best practices

This topic contains important information about support of our API, our requirements surrounding serial

calls, security, and your option of using encrypted files, as well as some best-practice tips to follow.

API Support and Updates

ExactTarget is continually improving the product and the technologies that support the product. The API

access to the product is regularly updated as well. We will make every effort to provide backward

compatibility for a reasonable duration for API calls that are phased out. Before you begin using the API,

please contact ExactTarget Support to confirm that you have the latest version of this documentation.

Note that the API uses HTTPS and other internet technologies. The API is meant for small- to medium-

sized datasets. For large results, such as large lists and large bulk export data, please contact your sales

representative for information on our batch export process.

Note: ExactTarget has regularly scheduled system maintenance every Friday night at 10:00PM until

Saturday morning at 4:00AM, during which time the API will be unavailable. Please be aware of this

maintenance window while planning your integration with ExactTarget. You can check on the status of the

ExactTarget system by using the diagnostics call.

Serial Calls and Retries

ExactTarget recommends that calls to the API be made in a serial fashion. For example, if you are

importing a list and sending the email to that list, the first step is to FTP the file and then issue the import

command. The second step is to receive confirmation of the import and then issue the email send

command.

Please do not run more than five async events at any one time. If you have initiated five async events, wait

until one of those events is completed before initiating another event. (If you need to exceed this limit,

contact ExactTarget Support for assistance.)

Likewise, if you need to retry a call, do not retry the call more than three times. If your program loops with

unlimited reattempts, ExactTarget will be forced to disable your API access in order to ensure system

performance for all clients.

Security

Security is always critical. It becomes even more important when supporting clients in a seamless and

highly integrated model. ExactTarget takes security very seriously and provides a variety of mechanisms to

ensure that individuals without the appropriate system privileges cannot access client information.


8

Encryption

All incoming and outgoing API communications can be performed using SSL.

Import files can optionally be encrypted using GnuPG encryption. See the FTP Instruction Guide PDF for

complete details on formatting import files.

Authentication

All API calls require a username and password for identification and authentication purposes. Each client's

administrator manages usernames and passwords through the ExactTarget application interface. You can

choose to create a username and password specifically for each remote procedure that may use the API.

Note: When you first set up a user, the user needs to log in to the application (through the application

interface) with the temporary password, at which point the user will be prompted for a new password.

Make sure that you follow this step for your API login(s) before you begin to construct calls. Also, make

sure that your API login password(s) contain XML-friendly characters only (avoid such characters as &, ",

', >, and <).

Once the username is authenticated, we authorize the activity that is being performed. The process of

authorization takes security rules, set by the client, and applies them to the specific username being used, to

ensure that the user is authorized to perform the activity requested.

Finally, object access rules ensure that authenticated users only have access to objects that they own. For

instance, a client’s employees have access to only that client’s content, tracking information, emails, and

subscribers.

Best Practices

The following list contains best practices to follow when using any third-party programming tool or object,

including the ExactTarget API:

� The ExactTarget API will time out only if the call exceeds 1800 seconds (30 minutes). With such

an extensive setting, any timeout that occurs typically occurs within the client web server or the

client script. If you're requesting large volumes of data, program your timeout settings

accordingly.

� Communication errors and outages are always a potential factor when communicating via the

Internet. Program accordingly.

� Logging is always an excellent best practice. As you begin using the ExactTarget API, we

recommend that you use success and failure logs to monitor all calls that your system has made.

Later, be sure to maintain at least a failure log for troubleshooting purposes. Log the following

data: date, time, error, XML posted, and XML received.

� Queuing is an additional recommendation. To avoid downtime in your application, queue any calls

that result in Error=0 or a communication error and reattempt the call after a period of time (such

as 15 minutes). Clear your queue once the calls have gone through.

� Follow standard XML best practices. For example, eliminate spaces between nodes and trim the

values within nodes. Do not attempt to pass illegal characters (<, >, &, "). If your data contains an

illegal character, use CDATA as follows:

<node><![CDATA[insert illegal character here]]></node>


9

� Use POST rather than GET. GET uses a querystring and concatenates your XML to the URL.

GET has some programmatic limitations for length and can result in an XML error indicating that

your code is bad or is missing a closing node. Use POST to avoid these issues.

� Be sure to URL-encode all input.

� Client-side integration with the use of Flash/ActionScript and Ajax (Asynchronous JavaScript and

XML) is becoming more common to build robust applications. If you're using these technologies,

do not embed your user authorization in code that resides in the client-side script. As a security

best practice, maintain your authorization (username and password) in your server-side proxy page

that's used to post your data to the API and return the response.


10

How to Construct Your Calling Application �� base xml format �� http construction �� results �� direct link to exacttarget via querystring

ExactTarget uses the Extensible Markup Language (XML) as a universal format to invoke API calls to

various systems used throughout the ExactTarget system. We support XML version 1.0 as defined in the

standard at http://www.w3c.org.

This documentation provides XML examples that can be mapped to HTTPS calls.

See also the full-fledged Visual Basic and ASP application code samples.

Base XML Format

Your XML file containing API calls to the ExactTarget application consists of the following elements:

� Version tag: The version tag must indicate version 1.0.

� Base attribute tag: The base attribute tag must indicate exacttarget.

� Authentication attribute: The first attributes after the base attribute tag must be a username and

password with the appropriate access rights to your ExactTarget application.

� System attribute: The ExactTarget API is broken up into the following systems: Subscriber, List,

Jobs, Tracking, and Email. Your API command will be contained within a set of <system> tags.

Here's an example of a fully formatted XML string that can be used to retrieve information from an

ExactTarget subscriber list with list ID 123456:

<?xml version="1.0" ?>

<exacttarget>

<authorization>

<username>username</username>

<password>password</password>

</authorization>

<system>

<system_name>list</system_name>

<action>retrieve</action>

<search_type>listid</search_type>

<search_value>123456</search_value>

<search_value2></search_value2>

</system>

</exacttarget>

XML Tag Tag Description

<username> The username associated with a user record in your ExactTarget security that

has the access rights necessary to perform the action specified in your API

calls.


11

<password> The password associated with the username.

HTTP Construction

XML can be passed in a URL querystring, using GET to build the querystring or manually constructing the

querystring. Another option is to post the data using HTTPPost.

GET

When using GET or manually constructing the querystring, you construct your call as follows:

https://www.exacttarget.com/api/integrate.asp?qf=xml&xml=xxx

Replace xxx with the XML that the API is to execute.

Here's an example of a fully formatted string:

https://www.exacttarget.com/api/integrate.asp?qf=xml&xml=<?xml

version="1.0"?><exacttarget><authorization><username>username</usern

ame>

<password>password</password></authorization><system><system_name>

subscriber</system_name><action>add</action><search_type>listid

</search_type><search_value>1234</search_value><search_value2>

</search_value2><values><Full__Name>Test

Person</Full__Name><Email__Address>[email protected]

</Email__Address></values></system></exacttarget>

For testing purposes, you can copy and paste your URL into a browser to verify the results of the call you

have created.

Note: When using a querystring or GET, be sure not to exceed URL size limitations. Your call will be

truncated if it exceeds the maximum length (approximately 2000 characters).

POST

When using the POST method, make sure that you include the following Request Headers in your POST:

� http_request.setRequestHeader("Content-type", "application/x-www-form-urlencoded");

� http_request.setRequestHeader("Content-length", parameters.length);

� http_request.setRequestHeader("Connection", "close");

Be sure to substitute your actual parameter length.

POST qf=xml&xml=xxx

Replace xxx with the URL-encoded XML that the API is to execute.

Results

The results of your call are returned in XML format.


12

Here's an example of the results returned for an API call creating a subscriber list:


<exacttarget>

<system>

<list>

<list_info>List was added successfully</list_info>

<list_description>1234567</list_description>

</list>

</system>

</exacttarget>

Notice that the resulting XML stream contains a message indicating whether the list creation was

successful and also the list ID associated with the newly created list.

Direct Link to ExactTarget via Querystring

You can allow users to navigate to a specific page in the ExactTarget application directly from your

website without requiring them to log in to the ExactTarget application. To do so, you place a link on your

site that passes the appropriate parameters to ExactTarget.

The parameters are as follows:

Parameter Description

username The username associated with a user record in your ExactTarget security that

has the access rights necessary to perform the action.

password The password associated with the username.

entityType The area of the ExactTarget application that you want to open.

Possible entityType values:

� email

� subscribers

� tracking

� libraries

� admin

entityID (optional) The system ID associated with the item that you want to open (email

ID, list ID, job ID).

If entityID is not provided, the main folder for the entityType (My Emails, for

example) will be displayed.

Here's an example of a link to a page that displays all subscribers on a specified list:


13

https://members.exacttarget.com/Login.aspx?username=username&passwor

d=password&entityType=subscribers&entityID=12345

After authenticating the username and password, ExactTarget will take the user directly to the subs_list.asp

page and display a list of subscribers on the list with list ID 12345.

Note: Be sure to URL-encode your characters.

See Also: Conventions and Other Information


Introduction to Application Code Sample


14

Conventions and Other Information �� code sample format �� identifiers (id codes) �� profile and preference attributes �� supported ascii

characters

This topic contains details specific to the code conventions you'll see in this documentation and instructions

for obtaining system identifiers and referencing profile and preference attributes.

Code Sample Format

For each API command, this documentation provides sample code showing how the API command is used.

The samples follow these conventions:

� Bold red text indicates values that are to be entered exactly as shown.

� Bold italic red text indicates value examples that are to be replaced with your input values.

� Lines highlighted in yellow are intended for certain clients only. See the explanation following the

code sample.

� Following the code sample, a table explains the expected input values.

� Each sample shows only the code for the action to be performed by that API call, not the entire

XML code required. (See Formatting Your Calling Application.)

See the Subscriber Add topic for an example of these elements.

Identifiers (ID Codes)

Your API calls will need to use one or more of the following system identifiers:

Identifier Description

Channel Member

ID

(Enterprise clients only) Member ID of your On Your Behalf (Dynamic One-

to-One) channel account.

To find the member ID of your channel account, go to your organizational

chart in the administrative area of the ExactTarget application. Double-click

the node containing the channel member to bring up the Account List

workspace, which shows the member ID for each channel member in that

node.

email ID System-generated unique ID of an email (the email itself, not any sends

associated with the email).

When you create an email using the API, the email ID (EID) is returned to

you.

To find the ID for an email through the ExactTarget application interface,


15

follow these steps:

1. Expand the email folder that contains the email so that the email

name is displayed in the workspace on the right.

2. Hover over the hyperlinked email name and look at your browser

status bar (you may need to turn on the status bar in your browser

View menu).

3. The email ID is the sequence of numbers following eid= in the URL

that you see in the status bar.

event ID ID associated with the Additional Info value that users can input into the

application if you have this optional feature enabled in your account. Contact

your ExactTarget representative for assistance if needed.

group ID System-generated unique ID of a group. This ID is available through the API

only; it is not displayed in the ExactTarget application interface. You obtain a

group ID by using the List Retrieve Groups (All Groups) command.

job ID System-generated unique ID of an email send (a job).

When you initiate an email send using the API, the job ID (JID) is returned to

you. You can retrieve all job IDs by using the Tracking Retrieve Job IDs

command.

To find the ID for an email send through the ExactTarget application interface,

follow these steps:

1. Expand the Tracking section so that the email send is displayed in the

workspace on the right.

2. Hover over the hyperlinked release date/time and look at your

browser status bar (you may need to turn on the status bar in your

browser View menu).

3. The job ID is the sequence of numbers following jid= in the URL that

you see in the status bar.

list ID System-generated unique ID of a subscriber list.

When you create a list using the API, the list ID (LID) is returned to you. You

can retrieve all list IDs by using the List Retrieve command.

To find the list ID through the ExactTarget application interface, open your list

folder in the list workspace and then choose the View Properties option for the

list. The LID is shown in the ID field of the Properties dialog box.

subscriber ID System-generated unique ID of a subscriber, based on the subscriber's email

address (a unique ID is generated for each email address in your subscriber

lists). This ID is available through the API only; it is not displayed in the

ExactTarget application interface. You obtain a subscriber ID by using the

Subscriber Retrieve command.


16

Profile and Preference Attributes

When passing profile or preference attributes, note the following:

� Any spaces in your attribute field name are represented as two underscores. For example, the

attribute Full Name is passed as Full__Name.

� Attribute field names specified in your calls are not case-sensitive. For example, ADDRESS1 and

Address1 are considered equivalent.

� Attribute field names specified in your calls must already exist in your account, and the field name

in your call must exactly match the field name defined in your account (with the case-sensitivity

and space exceptions noted above).

� If an attribute has been marked in the application as required, any subscriber that you add must

contain a value for that attribute.

� Profile attributes with restricted values (drop-down lists of values) are treated like required

attributes: any subscriber that you add must contain a value for that attribute, and the value must

exactly match one of the restricted values defined for the attribute.

� Preference attributes are also treated like required attributes. Only one of two values is accepted:

true or false. These values are not case-sensitive.

� The first character of an attribute value must be alphabetic (A to Z). Do not begin an attribute with

a number or any other kind of nonalphabetic character.

Supported ASCII Characters

The ASCII characters that ExactTarget supports in email addresses and attribute data values are listed in

the ExactTarget application's online help, which is accessible via the Help link in the upper-right corner of

the application window. Search for the index entry ASCII character support.

See Also: How to Construct Your Calling Application



17

Checking the Status of the ExactTarget API �� method �� results

Purpose: Check whether the ExactTarget API is currently online or down for maintenance.

Input: None.

Results: A status message is returned to you.

Additional

Info:

This call does not require the standard authentication node.

See the ExactTarget Support topic for information about scheduled weekly downtime.

Method

To request the current status of the ExactTarget system, use the following syntax:

<system>

<system_name>diagnostics</system_name>

<action>Ping</action>

</system>

Results

If the system is online and operating normally, the following status message is returned:


<exacttarget>

<system>

<diagnostics>

<Ping>Running</Ping>

</diagnostics>

</system>

</exacttarget>

If the system is currently down, Error 0 (system unavailable) will be returned.


Conventions and Other Information


18

Subscriber Management

Introduction to Subscriber Management

We provide a variety of ways to upload data to populate your email subscriber lists. The first load of

subscriber information is often performed through a batch file upload using the ExactTarget web-based

interface. Subsequent subscriber additions and updates often occur individually through our API.

Although the large file upload process is normally triggered using our web-based interface, it can be

remotely triggered using an available API.

Subscriber Add

�� method �� results

Purpose: Add a subscriber to a list.

Input: List ID; subscriber data (email address, status, and other attribute values).

Results: Subscriber ID for each subscriber successfully added is returned to you.

Additional

Info:

You can also add multiple subscribers at one time by uploading a comma-delimited or

tab-delimited file with subscriber data. See the List Import (Upload Trigger) API

command.

Method

To add a single subscriber, use the subscriber add command with the following syntax.

Note: This example includes the two default profile attributes: Full Name and Email Address. If you have

defined your own profile attributes in the ExactTarget application, replace the attribute references in these

code lines with your own attributes. You can include as many attributes as desired. Remember that spaces

in your attribute names must be replaced by two underscores, as described in Conventions and Code

Requirements.

<system>

<system_name>subscriber</system_name>

<action>add</action>




<values>

<Email__Address>[email protected]</Email__Address>

<status>active</status>

<Full__Name>Test Person</Full__Name>


19

<ChannelMemberID>5678</ChannelMemberID>

</values>

<update>true</update>

</system>


<search_value> The list ID of the ExactTarget list to which you want to add this subscriber.

<Email__Address> The subscriber's email address. This attribute is required of all subscribers.

<Full__Name> Example of a profile attribute.

<status> This tag has two possible values: unsub and active.

Specify unsub if you want to add the subscriber with the Unsubscribed status.

Specify active to add an active subscriber.

<Update> If the tag is set to true, the All Subscriber record will be created with the

information provided in the API commands.

Note: If the value is set to true and the record already exists on the list, an

error 14 will be returned and you would will need to execute a Subscriber Edit

call.

When this tag is set to false (or if the tag is missing), the subscriber will be

added to the specified list but the attribute values entered in the command will

be ignored if the subscriber already exists.

<ChannelMemberID> If you use the Enterprise version of ExactTarget, the channel member ID is

required for imports into an On Your Behalf (Dynamic One-to-One) client

database.

Results

The successful completion of this script will return a unique subscriber ID in the <subscriber_description>

field, which can subsequently be used to identify the subscriber.


<exacttarget>

<system>

<subscriber>

<subscriber_info>Subscriber was added/updated

successfully</subscriber_info>

<subscriber_description>12334566</subscriber_descriptio

n>

</subscriber>

</system>

</exacttarget>

If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine

to be implemented.


20

See Also: List Add

List Import (Upload Trigger)

How to Construct Your Calling Application


Subscriber Edit (Update)


Purpose: Update the attributes (including email address) and/or status of an existing subscriber.

Can be used to reactivate a subscriber who was placed on the master unsubscribe list.

Input: Email address; list ID or subscriber ID; unsubscribe reason (if applicable).

Results: Subscriber ID for each subscriber successfully updated is returned to you.

Additional

Info:

Two subscriber update variations are available, depending on whether you want to use

subscriber ID or list ID as the search data.

You can also update multiple subscribers at one time by uploading a comma-delimited

or tab-delimited file with subscriber data. See the List Import (Upload Trigger) API

command.

Method

The following code samples show the syntax for the two variations of the subscriber edit (update) method.

Note: These examples include the default profile attribute Full Name. If you have defined your own profile

attributes in the ExactTarget application, you can use your own attribute references in these code lines. You

can include as many attributes as desired. Remember that spaces in your attribute names must be replaced

by two underscores, as described in Conventions and Code Requirements.

Subscriber Update by List ID

To update a single subscriber by using the list ID, use the subscriber edit command with the following

syntax.

Note: If you use the All Subscribers list ID and you update the subscriber's status to Unsubscribed, this

status update will be propagated to all other lists; the subscriber will be unsubscribed from all lists.

However, if you use the All Subscribers list ID and you update the subscriber's status to Active, this status

update will be applied to the All Subscribers list only, not to any other lists. Use the All Subscribers list ID

if you're reactivating a subscriber who has been on the master unsubscribe list.

<system>


<action>edit</action>




21

<search_value2>[email protected]</search_value2>

<values>

<First__Name>User</First__Name>


<status>unsub</status>

<reason>insert your unsubscribe reason here</reason>


</values>

</system>

Subscriber Update by Subscriber ID

To update a single subscriber by using the subscriber ID, use the subscriber edit command with the

following syntax.

Note: If you choose to use subscriber ID as the search data for the subscriber edit command, note that you

cannot set a status. (The subscriber ID is the same for this subscriber across all lists; without a list ID, the

ExactTarget application does not know to which list the subscriber's status update should apply.)

<system>



<search_type>subid</search_type>


<search_value2></searchvalue2>

<values>

<First__Name>Scott2</First__Name>



</values>

</system>

Parameters


<search_type> Either listid or subid, depending on which variation of the method you choose

to use.

<search_value> The list ID of the ExactTarget list in which you want to update this subscriber,

or the subscriber ID of the subscriber you want to update.

<search_value2> When searching on list ID, enter the subscriber's email address as this tag's

value, for search purposes.

When searching on subscriber ID, leave this tag's value blank. (However, the

tag must still be included; do not omit this tag.)

<Email__Address> The subscriber's email address.

If you're updating the subscriber's email address, enter the new email address


22

in this field.

<Full__Name> Example of a profile attribute. Replace with the attribute(s) that you're

updating by specifying the attribute name and the updated attribute value.

<status> (Available when using the list ID search type only.) This tag has two possible

values: unsub and active.

Specify unsub if you want to unsubscribe the subscriber from the list.

Specify active if reactivating an unsubscribed subscriber.

<reason> (Applicable only when using the list ID search type and setting the status to

unsub.)

When you set a subscriber's status to unsubscribed, you can optionally include

the unsubscribe reason to be displayed in the application interface. If you do

not include a <reason> value, then the unsubscribe reason will be displayed to

users as "Unsubscribed by subscriber edit API call."

<ChannelMemberID> If you use the Enterprise version of ExactTarget, the channel member ID is

required for imports into an On Your Behalf (Dynamic One-to-One) client

database.

Results

The successful completion of this script will return a unique subscriber ID in the <subscriber_description>

field, which can subsequently be used to identify a subscriber.


<exacttarget>

<system>

<subscriber>

<subscriber_info>Subscriber was added/updated

successfully</subscriber_info>

<subscriber_description>12334566</subscriber_descriptio

n>

</subscriber>

</system>

</exacttarget>


to be implemented.




23

Subscriber Retrieve


Purpose: Retrieve all profile and preference attribute data entered for a subscriber on a specific

list, or retrieve all attribute data for a subscriber and all lists to which the subscriber

belongs.

Input: Email address and (optionally) list ID; or subscriber ID.

Results: All attribute values for the subscriber, or all attribute values and all lists for the

subscriber, are returned to you. The subscriber ID is included in the results.

Additional

Info:

Two subscriber retrieval variations are available, depending on whether you want to use

subscriber ID or list ID as the search data.

See List Retrieve Subscribers for a method of retrieving all subscribers from a specified

list.

Method

The following code samples show the syntax for the two variations of the subscriber retrieve method.

Subscriber Retrieve by List ID

To find a subscriber on a specific list, use the subscriber retrieve command with the list ID specified, as

follows:

<system>






<showChannelID></showChannelID>

</system>

To retrieve all the lists to which the subscriber belongs, in addition to the subscriber's profile data, leave the

list ID search value blank, as follows:

<system>




<search_value></search_value>



</system>


24

Subscriber Retrieve by Subscriber ID

If you know the subscriber ID, you can use the subscriber retrieve command with the subscriber ID, as

follows:

<system>







</system>

Parameters


<search_type> Either listid or subid, depending on which variation of the method you choose

to use.

<search_value> The list ID of any ExactTarget list to which this subscriber belongs, or the

subscriber ID of the subscriber you want to find.

To bring back all lists to which the subscriber belongs, specify listid as the

search_type and leave this tag with a blank value.

<search_value2> When searching with search_type listid, enter the subscriber's email address as

this tag's value, for search purposes.



<showChannelID> (Optional) If you use the Enterprise version of ExactTarget, you can use this

tag to bring back the member ID of the On Your Behalf (Dynamic One-to-

One) channel account with which the subscriber is associated. Leave the value

for this tag blank.

Results

The successful completion of this script will return the subscriber's data.

Here's an example of the results returned when searching by a specific list ID or subscriber ID (this

example includes the Enterprise-only showChannelID tag):


<exacttarget>

<system>

<subscriber>

<subid>125704849</subid>

<listid>63718</listid>


25

<list_name>Newsletter List</list_name>


<Status>Active</Status>

<Email__Type>HTML</Email__Type>

<First__Name>John</First__Name>

<Last__Name>Doe</Last__Name>

<Title />

<Region />

<showChannelID>123456</showChannelID>

</subscriber>

</system>

</exacttarget>

The following example shows the results returned when a list ID was not specified, to bring back all lists:

<?xmlversion="1.0"?>

<exacttarget>

<system>

<subscriber>



<list_name>NewsletterList</list_name>






<Title/>

<Region/>

</subscriber>

<subscriber>



<list_name>TechnologyUpdate</list_name>






<Title/>

<Region/>

</subscriber>

</system>

</exacttarget>


to be implemented.


26



Requesting Job Notifications

Subscriber Delete


Purpose: Delete a subscriber from your database, or remove a subscriber from a specified list.

Input: Email address and list ID; or subscriber ID.

Results: Deletion of subscriber or removal of subscriber from specified list. A confirmation

message is returned to you.

Additional

Info:

Two subscriber delete variations are available, depending on whether you want to delete

the subscriber entirely or remove the subscriber from a single list.

See also Subscriber Master Unsub (Master Unsubscribe List), which places the

subscriber on your Master Unsubscribe list. All new subscribers' email addresses are

checked against your Master Unsubscribe list and will not be added if a match is found,

whereas a deleted subscriber could appear in your database again from an import or

another creation method.

See also List Delete, which deletes a list and all subscribers on the list.

Method

The following code samples show the syntax for the two variations of the subscriber delete method.

Remove Subscriber from List

To remove a subscriber from a single list, use the following syntax. The subscriber will be removed from

the specified list but will not be deleted from other lists to which the subscriber may belong (unless the list

ID you use is that of the All Subscribers list, in which case the subscriber will be deleted entirely).

<system>


<action>delete</action>




</system>

Delete Subscriber

To delete a subscriber, use the following syntax:


27

<system>






</system>

Parameters


<search_type> Either listid or subid, depending on whether you're removing the subscriber

from a list or deleting the subscriber entirely.

<search_value> The list ID of the ExactTarget list from which you want to remove this

subscriber, or the subscriber ID of the subscriber you want to delete.

<search_value2> When using search_type listid, enter the subscriber's email address as this tag's

value.



Results

The successful completion of this script will return a confirmation message.


<exacttarget>

<system>

<subscriber>

<subscriber_info> Subscriber Deleted Successfully

</subscriber_info>

</subscriber>

</system>

</exacttarget>


to be implemented.




28

Subscriber Master Unsub (Master Unsubscribe List)


Purpose: Place a subscriber's (or multiple subscribers') email address on your Master Unsubscribe

list so that the email address is never added to any of your subscriber lists.

Input: Email address.

Results: Addition of subscriber(s) to your Master Unsubscribe list. A confirmation message is

returned to you.

Additional

Info:

Note: If you use the Enterprise version of ExactTarget, you cannot use this call to add a

new subscriber to your Master Unsubscribe list, because creating a subscriber requires

that you specify the channel member ID. To add a new subscriber to your Enterprise

Master Unsubscribe list, use the Subscriber Add call with the <status> tag value set to

Unsub.

See also Subscriber Delete, which removes the subscriber completely from your

database. All new subscribers' email addresses are checked against your Master

Unsubscribe list and will not be added if a match is found, whereas a deleted subscriber

could appear in your database again from an import or another creation method.

See also Subscriber Edit (Update), which allows you to reactivate a subscriber by

updating the subscriber's All Subscribers list status.

Method

To add one or more email addresses to your Master Unsubscribe list, use the following syntax:

<system>


<action>masterunsub</action>

<search_type>emailaddress</search_type>

<search_value>

<emailaddress>[email protected]</emailaddress>



</search_value>

</system>


<search_type> The only valid search_type is emailaddress.

<search_value> Email address to add to the Master Unsubscribe list. You can enter as many as

25 email addresses, each on its own line (only one email address per set of

<emailaddress> tags).

Results

The successful completion of this script will return output similar to the following:


29


<exacttarget>

<system>

<subscriber>

<subscriberunsub>

<emailaddress>[email protected]</emailadd

ress>

<status>masterunsub</status>

</subscriberunsub>

<subscriberunsub>


ress>


</subscriberunsub>

<subscriberunsub>


ress>


</subscriberunsub>

</subscriber>

</system>

</exacttarget>

If the email address was not passed, you'll receive the following output:

<subscriberunsub>

<emailaddress>Missing</emailaddress>

<status>Error</status>

</subscriberunsub>

If the email address is already on your Master Unsubscribe list, you'll receive output similar to the

following:

<subscriberunsub>


<status>subscriber address already exists</status>

</subscriberunsub>

If another kind of error occurs, the error code will be returned in XML format for the appropriate error

trapping routine to be implemented.




30

Master Unsub Retrieve


Purpose: Return information about subscribers currently on the Master Unsubscribe list (either all

subscribers on the list or subscribers added to it during a specified period).

Input: Date range (optional).

Results: Name, email address, and unsubscribe information about subscribers on your Master

Unsubscribe list are returned to you.

Additional

Info:

None.

Method

To retrieve data from your Master Unsubscribe list for a specific date range, use the following syntax:

<system>

<system_name>tracking</system_name>


<sub_action>masterunsub</sub_action>

<search_type/>

<search_value/>

<daterange>

<startdate>8/1/2003</startdate>

<enddate>9/1/2003</enddate>

</daterange>

</system>

To return all subscribers on the Master Unsubscribe list, use the following syntax:

<system>



<sub_action>masterunsub</sub_action>

<search_type/>

<search_value/>

<daterange/>

</system>


<search_type> and

<search_value>

Leave these tags' values blank. (Do not omit the tags.)

<daterange> (Optional) If you want to retrieve subscribers added to the Master Unsubscribe

list during a specific period, enter the dates within the <startdate> and

<enddate> tags in the format M/D/YYYY.


31

Results



<exacttarget>

<system>

<tracking>

<masterunsubscribed>

<subscriber>

<email_address>[email protected]</email_

address>

<name>Mary Smith</name>

<reason>unsubscribed by ET RMM service based

on subscriber reply email request</reason>

<unsub_date_time>8/1/2003 6:11:26

AM</unsub_date_time>

</subscriber>

<subscriber>

<email_address>[email protected]</email_a

ddress>

<name>Bob Smith</name>

<reason>unsubscribed by ET RMM service based

on subscriber reply email request</reason>

<unsub_date_time>8/1/2003 6:42:41

AM</unsub_date_time>

</subscriber>

</masterunsubscribed>

</tracking>

</system>

</exacttarget>


to be implemented.



FTAF (Forward to a Friend) Retrieve



32

Purpose: Return all subscribers added as a result of a specified email forwarded with the Forward

to a Friend feature (an advanced option in the ExactTarget application).

Input: Job ID of the email send whose Forward to a Friend results you want to track.

Results: All profile and preference attribute data for the subscribers added as a result of Forward

to a Friend is returned to you.

Additional

Info:

None.

Method

To retrieve subscriber data for all subscribers added as a result of responding to the Forward to a Friend

feature for a particular email send, use the following syntax:

<system>



<sub_action>ftaf</sub_action>

<search_type>jobID</search_type>


<search_value2/>

</system>


<search_value> Job ID of the email send whose Forward to a Friend results you're retrieving.

<search_value2/> Leave this tag's value blank. (Do not omit the tag.)

Results



<exacttarget>

<system>

<tracking>

<email_summary>

<email_name>August 27 Not-for-Profit

News</email_name>

<email_subject>August 27 Not-for-Profit

News</email_subject>

<date_sent>8/28/2002 8:20:00 AM</date_sent>

<lists>

<list>Full June 2 List</list>

</lists>

</email_summary>

<FTAF_summary>

<email_forwarders>12</email_forwarders>

<new_recipients>19</new_recipients>


33

<new_subscribers>4</new_subscribers>

</FTAF_summary>

<subscribers>

<subscriber>

<subscriberID>11690706</subscriberID>

<listID>12999</listID>

<firstname />

<lastname />

<email>[email protected]</email>

<type>HTML</type>

<Favorite__Color>red</Favorite__Color>

<FavoriteMusic>Rock</FavoriteMusic>

</subscriber>

<subscriber>



<firstname />

<lastname />


<type>HTML</type>

<Favorite__Color>Blue</Favorite__Color>

<FavoriteMusic>Jazz</FavoriteMusic>

</subscriber>

<subscriber>



<firstname />

<lastname />


<type>HTML</type>

<Favorite__Color>Green</Favorite__Color>

<FavoriteMusic>Country</FavoriteMusic>

</subscriber>

<subscriber>



<firstname />

<lastname />


<type>HTML</type>

<Favorite__Color>Orange</Favorite__Color>

<FavoriteMusic>Folk</FavoriteMusic>

</subscriber>

</subscribers>

</tracking>

</system>

</exacttarget>


34


to be implemented.




35

List Management

Introduction to List Management

List management consists of such tasks as creating lists, importing subscribers, retrieving information about

lists and subscribers, and refreshing groups.

Attributes (Account Info) Retrieve


Purpose: Retrieve the profile and preference attributes defined in your ExactTarget account.

Input: None.

Results: Details of your attribute definitions are returned to you.

Additional

Info:

See Subscriber Retrieve for a method of obtaining the attribute values entered for your

subscribers.

Method

To retrieve a list of the attributes defined in your account, use the following syntax.

<system>

<system_name>accountinfo</system_name>

<action>retrieve_attrbs</action>

<search_type/>

<search_value/>

</system>


<search_type> and

<search_value>


Results



<exacttarget>

<system>


36

<profile>

<attribute>

<name>Full Name</name>

<description>System default for subscribers

full name</description>

<default_value />

<data_type>text</data_type>

<required>False</required>

<min_size>0</min_size>

<max_size>2000</max_size>

<subscriber_editable>1</subscriber_editable>

<display>Full Name</display>

</attribute>

<attribute>

<name>Email Address</name>


email address</description>

<default_value />


<required>True</required>




<display>Email Address</display>

</attribute>

<attribute>

<name>Email Type</name>


email type</description>

<default_value>HTML</default_value>


<required>False</required>




<display>EmailType</display>

</attribute>

</profile>

</system>

</exacttarget>


to be implemented.




37

List Add


Purpose: Create a new subscriber list.

Input: List name and type.

Results: The list ID of the new list is returned to you.

Additional

Info:

Once you've created the list, you then add subscribers to the list. See Subscriber Add and

List Import (Upload Trigger).

Method

To create a subscriber list, use the following syntax:

<system>



<search_type></search_type>


<list_type>public</list_type>

<list_name>Monday’s List</list_name>

</system>


<search_type> and

<search_value>


<list_type> Possible values are as follows:

� Public: A public list is displayed in the Subscription Center, where

subscribers can opt in to or opt out of the list.

� Private: A private list is not displayed in the Subscription Center.

� Salesforce: If your ExactTarget application is integrated with

salesforce.com and this list will consist of salesforce.com contacts or

leads, enter Salesforce as the value for this tag.

<list_name> The name of the new list. If the list is public, this name will be displayed in the

Subscription Center.


38

Results

The successful completion of this script will return a unique list ID in the <list_description> field, which

can subsequently be used to identify the list.


<exacttarget>

<system>

<list>

<list_info>List was added successfully</list_info>


</list>

</system>

</exacttarget>


to be implemented.



List Edit (Rename)


Purpose: Rename a subscriber list.

Input: List ID.

Results: A confirmation message is returned to you.

Additional

Info:

None.

Method

To rename a subscriber list, use the following syntax:

<system>





<list_name>April06</list_name>


39

</system>


<search_value> The list ID of the ExactTarget list that you're renaming.

<list_name> The new name of the list. If the list is public, this name will be displayed in the

Subscription Center.

Results

The successful completion of this script will return output similar to the following.


<exacttarget>

<system>

<list>

<list_info>List was modified successfully</list_info>


</list>

</system>

</exacttarget>


to be implemented.



List Retrieve


Purpose: Retrieve full information about a subscriber list, retrieve the list ID for a list (by full or

partial list name), or retrieve all list IDs.

Input: List ID or list name.

Results: The list name, list type, last-modified date, subscriber count, unsubscribe count, and

bounce count are returned to you when you provide the list ID. This method also returns

information about the groups that belong to the list.

For a full or partial list name, the list ID is returned to you.

With no list ID or list name, all list IDs in your account are returned to you.


40

Additional

Info:

Three variations on the list retrieve command are available, depending on whether you

know the list ID and how much list information you want to retrieve.

Method

The following code samples show the syntax for the variations on the list retrieve command.

Retrieve All List Information by List ID

To retrieve information about a subscriber list, use the following syntax:

<system>





</system>


<search_value> The list ID of the ExactTarget list that you're retrieving.

Retrieve List ID by List Name

To retrieve the list ID when you know the list name (or part of the list name), use the following syntax:

<system>



<search_type>listname</search_type>


</system>


<search_value> The name (or partial name) of the list whose list ID you want to retrieve.

Retrieve All List IDs

To retrieve all list IDs in your account, use the following syntax:

<system>



<search_type>listname</search_type>


</system>


41


<search_value> Leave the value for this tag blank. Do not omit the tag.

Results

The successful completion of these scripts will return output similar to the following. In all cases, if an

error occurs, the error code will be returned in XML format for the appropriate error trapping routine to be

implemented.

Retrieve All List Information by List ID


<exacttarget>

<system>

<list>

<list_name>API-API Test List</list_name>

<list_type>Public</list_type>

<modified>8/18/2003 10:11:59 AM</modified>

<subscriber_count>129</subscriber_count>

<active_total>126</active_total>

<held_count>1</held_count>

<bounce_count>2</bounce_count>

<unsub_count>0</unsub_count>

</list>

</system>

</exacttarget>

These results include the following pieces of information:

� List type: The list type is one of the following:

o Master: This list is your All Subscribers list.

o Public: The list is defined in your account as a public list (meaning that it is shown on

your Profile Center page).

o Private: The list is defined in your account as a private list.

o Salesforce: The list is marked in your account as a Salesforce list.

o Virtual: This type is displayed when what's being returned is actually a group, not a list.

� Subscriber count: Total number of subscribers on the list.

� Active total: Number of subscribers with the Active status on the list.

� Held count: Number of subscribers with the Returned status on the list.

� Unsub count: Number of subscribers with the Unsubscribed status on the list.


42

Retrieve List ID by List Name


<exacttarget>

<system>

<list>


</list>

</system>

</exacttarget>

Retrieve All List IDs


<exacttarget>

<system>

<list>






</list>

</system>

</exacttarget>



List Import (Upload Trigger)

�� method �� results �� mapping example

Purpose: Import new or updated subscribers en masse from a comma-delimited or tab-delimited

file into an existing subscriber list.

Input: List ID, filename, and attribute mappings.

Results: A confirmation message is returned to you by XML, and a log file of any subscribers

who could not be imported will be emailed to you if you provide an email address.

Additional

Info:

The first part of the import process is to create the import file and upload it to the

ExactTarget FTP site.

The subscriber list into which you want to import the subscribers must already exist. See


43

List Add to create a new list.

After you've completed the list import method, you can check on the status of the import

by using the List Import Status Check method.

See Subscriber Add for a method of adding a single subscriber.

Method

The first step is to create a tab-delimited TXT or comma-delimited CSV file with subscriber data. You'll

map the data columns in the TXT or CSV file to your ExactTarget attribute names in your API call. See the

attribute mapping example at the end of this topic.

See the FTP Instruction Guide PDF for complete details on using the ExactTarget FTP site.

Upload your uniquely named import file by dragging and dropping it at the FTP site:

ftp://ftp.exacttarget.com

Trigger the import of this data into your ExactTarget account by using the List Import command, with the

following syntax:

<system>


<action>import</action>



<file_name>filename.txt</file_name>

<email_address>[email protected]</email_address>

<file_type>tab</file_type>

<column_headings>true</column_headings>

<file_mapping>

<field>Email Address</field>

<field>full name</field>

<field>ChannelMemberID</field>

</file_mapping>

<import_type>0</import_type>

<returnid>true</returnid>

<encrypted>false</encrypted>

<encrypt_format></encrypt_format>

</system>

If you want to update multiple subscriber lists with the data in your import file, you can specify multiple

list IDs by replacing the <search_value> tag with the following syntax:

<search_values>




</search_values>


44

Note: If you use the All Subscribers list ID and you update the subscriber's status to Unsubscribed, this

status update will be propagated to all other lists; the subscriber will be unsubscribed from all lists.

However, if you use the All Subscribers list ID and you update the subscriber's status to Active, this status

update will be applied to the All Subscribers list only, not to any other lists.


<search_value> The list ID of the ExactTarget list or lists into which you want to import these

subscribers.

<file_name> The name of the import file you uploaded to the FTP site.

<email_address> The email address at which you want to receive confirmation when the import

completes, along with a log file of any unsuccessful import attempts.

<file_type> If your import file is tab-delimited, enter tab as the value for this tag. If it's

comma-delimited, enter csv.

<column_headings> If your import file contains a row of column headings, enter true as the value

for this tag. If your import file contains import data only, with no headings,

enter false.

<file_mapping> In this section, create a <field> line for every column in your file. Between the

<field> tags, enter the profile or preference attribute name as it's defined in

your ExactTarget account.

See the attribute mapping example at the end of this topic.

If the import file contains a field that you don't want to map, enter

<field>skip</field> for the line of your XML code that corresponds to that

field in your import file.

Remember: Email address is a required field. Your XML must contain an

email address mapping.

Note: If you use the Enterprise version of ExactTarget and you're importing

into an On Your Behalf (Dynamic One-to-One) channel member account, you

must include the ChannelMemberID mapping field. (In your import file, the

field value should be the channel member name.)

<import_type> Value of 0: Add new subscribers from the source list but do not update values

of any subscribers already on the destination list

Value of 1: Add new subscribers from the sources list and update values of

any subscribers already on the destination list

Value of 10: Update the values of any subscribers already on the destination

list but do not add any new subscribers from records on the source list

<returnid> If you want the import ID to be returned to you in the XML output, enter true.

Otherwise, enter false as the value for this tag.

If you want to check on the status of this import using the List Import Status

Check, you'll need the import ID.


45

<encrypted> If your import file is encrypted using GnuPG, enter true as the value of this

tag. If the file is not encrypted, you can either omit the tag or set it to false.

<encrypt_format> If your import file is encrypted, specify the encryption type, either binary or

ascii.

Results

The successful completion of this script will launch the import process and return a confirmation message.

If you chose to receive the import ID, you'll see the <importid> value.


<exacttarget>

<system>

<list>

<import_info>Your file is being imported. You will

receive an email when it completes.</import_info>

<importid>979804</importid>

</list>

</system>

</exacttarget>


to be implemented.

Mapping Example

This topic provides sample code for mapping your attributes.

In this example, the account contains the following profile and preference attributes:

� City

� Email Address

� First Name

� Greeting

� Indianapolis Metro Region

� Last Name

� Money Spent This Fiscal Year

� Catalog Preference

� HTML Email

� Weekly Survey Email


46

In this example, the import file contains the following fields, in order:

� f_name

� l_name

� city

� ST

� zip

� region

� email

� greeting

� catalog

� html

Here's the XML system statement for importing this data into the account's subscriber list with ID 112233:

<system>





<file_name>998770import.csv</file_name>

<email_address>[email protected]</email_address>

<file_type>csv</file_type>

<column_headings>true</column_headings>

<file_mapping>


47

<field>First Name</field>

<field>Last Name</field>

<field>City</field>

<field>skip</field>

<field>skip</field>

<field>Indianapolis Metro Region</field>

<field>Email Address</field>

<field>Greeting</field>

<field>Catalog Preference</field>

<field>HTML Email</field>

</file_mapping>

<update_add>0</update_add>

<returnid>true</returnid>

<encrypted>false</encrypted>

<encrypt_format></encrypt_format>

</system>

Notice the two fields that are marked to be skipped. The state and zip code values in the import file do not

exist as profile attributes in the account, and the skip value tells the system that those columns in the import

file need to be skipped.

Notice also that the XML code contains the names of the attributes exactly as they are defined in the

application.

See Also: FTP Instruction Guide (PDF)



List Import Status Check


Purpose: Request an update on the status of an import.

Input: Import ID.


Additional

Info:

The import ID is obtained by requesting it when triggering the import with the List

Import (Upload Trigger) method.

Method

To request an update on the status of an import, use the following syntax:


48

<system>



<sub_action>importstatus</sub_action>


</system>


<search_value> The import ID, which you request when you trigger the import with the List

Import (Upload Trigger) method.

Results

The successful completion of this script will return a status message.


<exacttarget>

<system>

<list>

<import_info>Complete</import_info>

<importid>979804</importid>

</list>

</system>

</exacttarget>

Four possible statuses can be returned:

� Initialized: The request to import the file has been received and is waiting in the queue.

� In Process: The import is underway.

� Complete: The import is done.

� Error: An error has occurred. Contact ExactTarget Support for assistance.

If an error occurs at the time that the XML command is submitted, the error code will be returned in XML

format for the appropriate error trapping routine to be implemented.



List Retrieve Subscribers



49

Purpose: Retrieve the profile and preference attributes for all subscribers (or all subscribers with a

certain status) on a specified list.

Input: List ID of the list and (optionally) subscriber status to use as a filter.

Results: All profile and preference attribute values for the subscribers are returned to you.

Additional

Info:

See also Subscriber Retrieve, the method for pulling back information about a single

subscriber.

Method

To retrieve all subscribers on a list, use the following syntax:

<system>


<action>retrieve_sub</action>



</system>

To filter by subscriber status, add the <search_status> tag, as follows:

<system>


<action>retrieve_sub</action>



<search_status>Active<search_status>

</system>


<search_value> The list ID of the ExactTarget list whose subscribers you want to retrieve.

<search_status> (Optional) Possible values to use as a filter for your results are as follows:

� Active

� Unsubscribed

� Returned

� Undeliverable

� Deleted

Results

The successful completion of this script will return the profile and preference attributes for each subscriber,

as shown in this example:


50


<exacttarget>

<system>

<list>

<subscribers>

<subscriber>

<Email__Address>[email protected]</Email__Ad

dress>



<firstName>Bob</firstName>

<lastName />

<fullname />

<Zip__Code />

<Account />

</subscriber>

<subscriber>

<Email__Address>[email protected]</Email__A

ddress>



<firstName>Mary</firstName>

<lastName>Smith</lastName>

<fullname />

<Zip__Code />

<Account />

</subscriber>

</subscribers>

</list>

</system>

</exacttarget>


to be implemented.



List Delete



51

Purpose: Delete a list and all subscribers who belong to the list.

Input: List ID.


Additional

Info:

See also Subscriber Delete, the method for deleting a single subscriber or removing a

subscriber from a single list.

Method

To delete a list, use the following syntax.

Note: When you delete a list, you're permanently deleting all of the subscribers on the list as well.

<system>





</system>


<search_value> The list ID of the ExactTarget list you want to delete.

Results

The successful completion of this script will return a confirmation message, along with the list ID of the

deleted list:


<exacttarget>

<system>

<list>

<list_info>List was deleted successfully</list_info>


</list>

</system>

</exacttarget>


to be implemented.




52

List Retrieve Groups (All Groups)


Purpose: Retrieve all groups in your account.

Input: None.

Results: The ID, name, description, and parent list ID of all groups in your account are returned

to you.

Additional

Info:

None.

Method

To retrieve all groups in your account, use the following syntax:

<system>


<action>retrievegroups</action>

<search_type>groups</search_type>

</system>

Results

The successful completion of this script will return the unique group ID in the <groupID> field, which can

subsequently be used to identify the group. The <parentlistID> field displays the list ID of the ExactTarget

subscriber list from which the group was created.


<exacttarget>

<system>

<list>

<groups>

<group>

<parentlistID>529007</parentlistID>

<groupID>530833</groupID>

<groupName>Marion County

Subscribers</groupName>

<description>Marion County

Subscribers</description>

</group>

<group>



<groupName>New Customers</groupName>

<description>Subscribers with Accounts 1

Year or Less</description>

</group>


53

<group>



<groupName>Hamilton County

Subscribers</groupName>

<description>Hamilton County

Subscribers</description>

</group>

</groups>

</list>

</system>

</exacttarget>


to be implemented.



List Refresh Group


Purpose: Refresh the membership of an attribute-based (rule-based) group to reflect any changes

to your subscribers' attribute values.

Input: Group ID.

Results: The async ID for this refresh request is returned to you.

Additional

Info:

The group ID is obtained by means of the List Retrieve Groups (All Groups) command.

The async ID can be used to request a status update on the refresh, using the Group

Refresh Status Check command.

A group is created in one of three ways: with random sampling, with the constant

interval method, or with rules based on profile and preference attributes. Only rule-based

groups can be refreshed.

If you want to refresh multiple groups, you need to send a separate call for each group.

You cannot refresh multiple groups in a single call.

Method

To refresh a rule-based group, use the following syntax:

<system>


54


<action>refresh_group</action>

<sub_action/>


<search_value2/>

</system>


<search_value> The group ID, which you obtain by means of the List Retrieve Groups (All

Groups) command.

Each call can contain only one group ID. You cannot refresh multiple groups

in a single call.

<sub_action> and

<search_value2>

Leave the values for these tags blank. (Do not omit these tags.)

Results

The successful completion of this script will return the <groupAsyncID> value, which you can use to check

the status of this refresh with the Group Refresh Status Check command.


<exacttarget>

<system>

<list>

<groupRefresh>


<groupAsyncID>40594104</groupAsyncID>

</groupRefresh>

</list>

</system>

</exacttarget>

If the group ID you supplied belongs to a group based on random sampling or constant interval rather than

on attribute rules, you'll receive the following result:


<exacttarget>

<system>

<list>

<error>101</error>

<error_description>Error occurred during the group

refresh event</error_description>

</list>

</system>

</exacttarget>

If an error in your call occurs, the error code will be returned in XML format for the appropriate error

trapping routine to be implemented.


55



Group Refresh Status Check (Batch Inquire)


Purpose: Request an update on the status of a group refresh.

Input: Async ID (ID generated for the refresh request).


Additional

Info:

The async ID is obtained from the List Refresh Group command.

Method

To request an update on the status of a group refresh, use the following syntax:

<system>

<system_name>batch</system_name>

<action>inquire</action>

<sub_action/>

<search_type>batchid</search_type>


<search_value2/>

</system>


<search_value> The batch ID is the async ID, which you obtain by means of the List Refresh

Group command.

<sub_action> and

<search_value2>

Leave the values for these tags blank. (Do not omit these tags.)

Results

The successful completion of this script will return a status message.


<exacttarget>

<system>

<Batch>


56

<batchid>40594104</batchid>

<status>Completed</status>

<filename></filename>

</Batch>

</system>

</exacttarget>

Four possible statuses can be returned:

� Init: The request to import the file has been received (initialized) and is waiting in the queue.

� Evaluating: The import is underway.

� Completed: The import is done.

� Error: An error has occurred. Contact ExactTarget Support for assistance.

The <filename> field is not relevant to this request (the batch inquire command is primarly used for

checking the status of batch file exports) and can be ignored.

If an error occurs at the time that the XML command is submitted, the error code will be returned in XML

format for the appropriate error trapping routine to be implemented.




57

Email Management

Introduction to Email Management

Using API calls, you can create HTML paste emails, customize the text versions of emails, retrieve the

body (content) of an email, and retrieve all email IDs.

Email Retrieve All (Email IDs)

�� method �� results.

Purpose: Retrieve all email IDs or filter by email name and/or date range.

Input: Start date and end date and/or email name. (You also have the option of not specifying

any filters, to return all email IDs in your account.)

Results: The email IDs, names, subject lines, created dates, and category IDs are returned to you.

Additional

Info:

None.

Method

To retrieve all email IDs, use the following syntax:

<system>

<system_name>email</system_name>


<sub_action>all</sub_action>

<search_type></search_type>



<daterange></daterange>

</system>

To retrieve the email ID for a specific email name, use the following syntax:

<system>




<search_type>emailname</search_type>

<search_value>Welcome to Fortune One!</search_value>



58

<daterange></daterange>

</system>

To retrieve the email ID of every email created during a specific period, use the following syntax:

<system>




<search_type>daterange</search_type>



<daterange>



</daterange>

</system>

To retrieve the email ID of an email by specifying the email name and the period in which it was created,

use the following syntax:

<system>




<search_type>emailnameanddaterange</search_type>

<search_value>Welcome to Fortune One!</search_value>


<daterange>



</daterange>

</system>


<search_value> (Optional) If using the emailname or emailnameanddaterange search type,

enter the email name as the value for this tag. Otherwise, leave blank.

<search_value2> Leave the value for this tag blank. (Do not omit the tag.)

<daterange> (Optional) If using the daterange or emailnameanddaterange search type,

enter the start date and end date in the format M/D/YYYY in the <startdate>

and <enddate> tags. Otherwise, leave <daterange> blank.

Results


<?xml version="1.0"?>

<exacttarget>


59

<system>

<email>

<emaillist>

<emailid>104022</emailid>

<emailname>HTML Training</emailname>

<emailsubject>Northern

Outfitters</emailsubject>

<emailcreateddate>3/1/2004</emailcreateddate>

<categoryid>75163</categoryid>

</emaillist>

<emaillist>


<emailname>Conversion Tracking</emailname>

<emailsubject>Conversion Tracking Advanced

Test</emailsubject>



</emaillist>

<emaillist>


<emailname>ET 04 Demo Email</emailname>

<emailsubject>ET 04 Demo Email</emailsubject>



</emaillist>

</email>

</system>

</exacttarget>


to be implemented.



Email Add HTML Paste


Purpose: Create an email from HTML that you send to the ExactTarget application via an API

call.


60

Input: Email name, subject, and body. Body can be embedded in call or uploaded as a separate

file to the FTP site.

Results: The email ID of the newly created email is returned to you.

Additional

Info:

This API call is available if you have the advanced HTML paste feature enabled in your

account.

You have the option of either including the email content in the call itself or referencing

a file on the ExactTarget FTP site to be used as the email content.

Note: Please note the following:

� The maximum size allowed for the email body is 100K.

� ExactTarget supports HTTP post only.

� If certain special characters appear in your email content, you must substitute

the HTML code for the character to ensure that the character is passed

correctly.

o Ampersand: Replace & with %26

o Percent: Replace % with %25

o Pound: Replace # with %23

� Your email must include an unsubscribe link and your physical mailing address,

per the CAN-SPAM Act.

Here's sample code for an unsubscribe link:

Go <a href="%%account_info_url%%">here</a> to leave

this mailing list or <a

href="%%account_info_url%%">modify</a> your email

profile.

Here's sample code for the physical mailing address reference:

<table cellpadding="2" cellspacing="0" width="600"

ID="Table5" Border=0><tr><td><font face="verdana"

size="1" color="#444444">This email was sent by:

<b>%%Member_Busname%%</b><br>%%Member_Addr%%

%%Member_City%%, %%Member_State%%,

%%Member_PostalCode%%,

%%Member_Country%%<br><br></td></tr></table>

� You can create dynamic content (in which a subscriber's attribute values control

the content that the subscriber sees) by means of XML statements in your email

body. See Creating Dynamic Content with XML.

� The email content — whether embedded in your call or located in a separate

uploaded file — must be contained within a CDATA tag.

Refer to the online help within the ExactTarget application for further details on HTML

paste emails, including a list of possible substitution strings (merge fields) that you can

insert into the email.

See also Email Add Text Version, if you want to customize the text version of the email.

Method

The following code samples show the syntax for the two variations of the email creation method.

Email Content Contained within Call

To create an HTML paste email with the content inserted into your call, use the following syntax:


61

<system>



<sub_action>HTMLPaste</sub_action>

<category></category>

<email_name>Your email name</email_name>

<email_subject>Your email subject line</email_subject>

<email_body><![CDATA[Your HTML email body]]></email_body>

</system>

Email Content in File Uploaded to FTP Site

To create an HTML paste email with content from a separate file, you first need to upload the file to the

FTP site:


For complete details on using the ExactTarget FTP site, see the FTP Instruction Guide PDF.

Then submit your call, using the following syntax:

<system>



<sub_action>HTMLPaste</sub_action>

<category></category>

<email_name>Your email name</email_name>

<email_subject>Your email subject line</email_subject>

<file_name>Filename</file_name>

</system>

Parameters


<category> Leave the value for this tag blank. (Do not omit the tag.)

<email_name> The (internal) name of the email.

<email_subject> The subject line that will appear to subscribers.

<email_body> (Included when using the option of embedding the content in the email.)

The body of your email, including the unsubscribe link and your physical

mailing address. The content goes inside the CDATA tag so that the HTML

can be sent to the ExactTarget system.

Refer to the Additional Info section at the top of this help topic for the

requirements that this section of your call must meet.

See Creating Dynamic Content with XML if you'd like to use dynamic content


62

in your email body.

<file_name> (Included when using the option of referencing a separate file.)

The name of the file that you uploaded to the ExactTarget FTP site.

Refer to the Additional Info section at the top of this help topic for the

requirements that this uploaded file must meet.

Results

The successful completion of this script will return the email ID.


<exacttarget>

<system>

<email>

<emailID>44180</emailID>

</email>

</system>

</exacttarget>


to be implemented.




Email Add Text Version


Purpose: Create the text version of an email, which will be displayed to any subscriber whose

email client does not support HTML email.

Input: Email ID and text body. Body can be embedded in call or uploaded as a separate file to

the FTP site.


Additional

Info:

Note: See Email Add HTML Paste for important information about the requirements for

the email body.

Refer to the online help within the ExactTarget application for further details on HTML


63

paste emails and their text versions.

Method

After you've created the HTML paste email, you can create and send the text version as well. ExactTarget

automatically generates the text equivalent of all emails. However, you can overwrite the default text

version with your own, using one of the following variations.

Email Content Contained within Call

If you're embedding the content within the call, use the following syntax:

<system>



<sub_action>text</sub_action>

<search_type>emailid</search_type>


<email_body><![CDATA[Your text email body]]></email_body>

</system>

Email Content in File Uploaded to FTP Site

To use content from a separate file, you first need to upload the file to the FTP site:



Then submit your call, using the following syntax:

<system>



<sub_action>text</sub_action>



<file_name>Filename</file_name>

</system>

Parameters


<search_value> The email ID of the email whose text version you're replacing.

<email_body> (Included when using the option of embedding the content in the email.)

The body of your text version, including the unsubscribe link and your

physical mailing address.


64

See Email Add HTML Paste for important information about the requirements

for the email body.

<file_name> (Included when using the option of referencing a separate file.)

The name of the file that you uploaded to the ExactTarget FTP site.

See Email Add HTML Paste for important information about the requirements

for the email body.

Results

The successful completion of this script will return a confirmation message.


<exacttarget>

<system>

<email>

<email_info>Email updated successfully/email_info>

</email>

</system>

</exacttarget>


to be implemented.



Email Retrieve Body


Purpose: Retrieve the body of the HTML version of any email in your account.

Input: Email ID.

Results: The content of the email body is returned to you.

Additional

Info:

The following data is not included in the HTML returned to you:

� Any dynamic content.

� Header content.

� Footer content.

Also note that if the email was created from a standard template, only the formatting of


65

the body will be returned, not the content of the content boxes in the email. (See the

example in the Results section.)

Method

To retrieve all email IDs, use the following syntax:

<system>



<sub_action>htmlemail</sub_action>





</system>


<search_value> The email ID of the email whose body you're retrieving.

<search_value2> and

<search_value3>

Leave the values for these tags blank. (Do not omit the tags.)

Results



<exacttarget>

<system>

<email>


<htmlbody><![CDATA[<custom name="opencounter"

type="tracking"><body bgcolor="#ffffff"

text="#000000"><table cellspacing=0 cellpadding=0

border=1 bordercolor=#6666FF bgcolor=#FF9900

width=600 align=center><tr><td><table

cellpadding="0" cellspacing="0" border="0"

bordercolor="" width="100%"

bgcolor="#FF9900"><tr><td

valign="top" align="center"><a

href="http://www.exacttarget.com"><img

src="http://images.exacttarget.com/5920479408612.gi

f"

border=0></a></td></tr></table></td>

<p> </p>

<h2 style="font-family: Georgia, serif;">Northern

Trails</h2>


66

<p style="color: #ff00ff;"><span style="font-

weight: bold;">Welcome to the inaugural issue of

the Northern Trails Times!</span> We hope that you

enjoy your subscription.</p>

<table x-use-null-cells

style="x-cell-content-align: top;

width: 100%;

border-spacing: 0;"

cellspacing=0

width=100%>

<col style="width: 50.342%;">

<col style="width: 49.658%;">

<tr valign=top>

<td style="padding-right: 10px;

padding-left: 10px;

border-left-style: None;

border-top-style: None;

border-right-style: None;

border-bottom-style: None;

background-color: #ff97ff;"

bgcolor=#FF97FF

width=50.342%>

<p style="font-weight: bold;">What's new this

week:</td>

<td rowspan=3

colspan=1

style="padding-right: 10px;

padding-left: 10px;

border-top-style: None;


border-bottom-style: None;"

width=49.658%>

<p style="font-weight: bold; font-style:

italic;">Coming soon!</p>

<ul style="list-style: square;"

type=square>

<li class=kadov-p><p>Cold-weather protection

without the bulkiness!</p></li>

<li class=kadov-p><p><span>Tips for packing

light.</span></p></li>

</ul></td></tr>

<tr valign=top>


padding-left: 10px;





bgcolor=#FF97FF


67

width=50.342%>

<p><a

href="http://www.northertrails.com/hikingboots.htm"

target=_blank>Hiking boots, great for checking out

fall colors.</a></td>

<td_null></tr>

<tr valign=top>


padding-left: 10px;





bgcolor=#FF97FF

width=50.342%>

<p><a

href="http://www.northerntrails.com/raingear.htm"

target=_blank>Raingear, a necessity in uncertain

climates.</a></td>

<td_null></tr>

</table>

<p>Check out our Web site for more!</p>

<p> </p>

<p> </p>

<p> </p>

<table cellpadding="2" cellspacing="0" width="600"

ID="Table5" Border=0><tr><td><font face="verdana"

size="1" color="#444444">This email was sent by:

<b>%%Member_Busname%%</b><br>%%Member_Addr%%

%%Member_City%%, %%Member_State%%,

%%Member_PostalCode%%,

%%Member_Country%%<br><br></td></tr></table><a

href="%%profile_center_url%%" alias="Update

Profile">Update Profile</a><a

href="%%ftaf_url%%"><img

src="http://www.exacttarget.com/members/newsletters

/gfx/ forwardafriendicon.gif" border="0"></a>

</body>]]></htmlbody>

</email>

</system>

</exacttarget>

If the email you retrieved was built from a standard template (with content boxes), you'll receive output

similar to the following. Notice that the text within the content boxes was not returned.


<exacttarget>

<system>

<email>



68

<htmlbody><![CDATA[<body bgcolor="#ffffff"

text="#000000"><table cellspacing=0 cellpadding=0

border=1 bordercolor=#6666FF bgcolor=#FF9900

width=600 align=center><tr><td><table cellpadding=

"0" cellspacing="0" border="0" bordercolor=""

width="100%" bgcolor="#FF9900"><tr><td valign="top"

align="center"><a

href="http://www.exacttarget.com"><img

src="http://images.exacttarget.com/5920479408612.gi

f"

border=0></a></td></tr></table></td></tr><tr><td><t

able cellpadding="12" cellspacing="0" border="0"

width="100%" height="100%">

<tr>

<td rowspan="5" height="16%" width="40%"

valign="top"><custom name="cell1"

type="content"></td>

<td height="16%" width="60%" valign="top"><custom

name="cell2" type="content"></td>

</tr>

<tr>

<td valign="top"><custom name="cell10"


</tr>

<tr>



</tr>

<tr>



</tr>

<tr>



</tr>

<tr>

<td width="100%" height="16%" colspan="2"



</tr>

<tr>




</tr>

<tr>




</tr>

<tr>


69




</tr>

<tr>




</tr>

<tr>


valign="top"> <custom name="cell8" type="content">

</td>

</tr>

<tr>


valign="top"> <custom name="cell9" type="content">

</td>

</tr>

</table></td></tr></table><custom

name="opencounter"

type="tracking"></body>]]></htmlbody>

</email>

</system>

</exacttarget>


to be implemented.




70

Jobs (Remote Triggers)

Introduction to Jobs (Remote Sending)

A job is an email send. You can trigger a mass email send through an API call. You can also send an email

to a single subscriber, which is a special feature available only through an API call.

Job Send (Mass Email)


Purpose: Send an email to a subscriber list or group.

Input: Email ID, list ID(s) and/or group ID(s), and parameters of the email send.

Results: A confirmation message with the job ID is returned to you.

Additional

Info:

An email sent through an API call will be accessible in the ExactTarget application

interface in the same way as an email sent through the application interface. All

personalization built into the email, reply mail management (if you have this advanced

feature enabled in your account), and tracking function the same for emails sent by either

method.

See also Job Send Single, to send a single email.

Method

To send an email from your ExactTarget account to one or more subscriber lists or groups, use the

following syntax:

<system>

<system_name>job</system_name>

<action>send</action>



<from_name></from_name>

<from_email></from_email>

<additional></additional>

<multipart_mime>false</multipart_mime>

<track_links>true</track_links>

<send_date>immediate</send_date>

<send_time></send_time>

<lists>

<list>12345</list>


71

<list>12346</list>

</lists>

<suppress>

<list>12345</list>

<list>12346</list>

</suppress>

<test_send>true</test_send>

</system>


<search_value> The email ID of the email that you want to send.

<from_name> and

<from_email>

If you have the advanced multiple-From option enabled in your account, enter

the From name and email address to display on this email. If you do not have

this option enabled, leave the values for these tags blank (the Email Display

Name and Email From Address defined in your account settings will be used).

If you're using the Enterprise version of the application and you're sending this

email for an On Your Behalf (Dynamic One-to-One) channel member, enter

@@ChannelMemberDisplayName@@ as the <from_name> value and

@@ChannelMemberEmail@@ as the <from_email> value.

<additional> If this feature is enabled in your account, specify additional information for the

job in this tag. Otherwise, leave the value for this tag blank.

<multipart_mime> To send the email in multiple parts for multipart MIME compatibility, enter

true as the value for this tag. Otherwise, enter false.

<track_links> If you want to track how many subscribers click the hyperlinks in this email,

enter true as the value for this tag. Otherwise, enter false.

<send_date> You have two options for specifying when the email will be sent:

� Immediate: Enter immediate as the value if you want to send the

email as soon as the job is processed.

� M/D/YYYY: Enter a date in the format M/D/YYYY if you want to

schedule a date and time for the email to be sent.

<send_time> If you entered a send date, specify the time, in the format H:MM (using a 24-

hour clock).

<list>

The list ID and/or group ID of the subscriber list(s) and/or group(s) to whom

this email should be sent.

The group ID is obtained through the List Retrieve Groups (All Groups)

command.

<suppress> The list ID and/or group ID of the subscriber list(s) and/or group(s) that should

be suppressed from this send..

The group ID is obtained through the List Retrieve Groups (All Groups)


72

command.

<test_send>

If you want to suppress this job from appearing in Performance Reports, enter

true as the value. The job will appear in the Tracking of the application;

however, it will not be available in Performance Reports.

Results

The successful completion of this script will return the job ID in the <job_description field>, which you can

subsequently use to identify this email send.


<exacttarget>

<system>

<job>

<job_info>Job was successfully created.</job_info>

<job_description>2030602</job_description>

</job>

</system>

</exacttarget>


to be implemented.



Job Send Single


Purpose: Send an email to a single subscriber.

Input: Email ID and subscriber ID.

Results: A confirmation message with the job ID is returned to you.

If the subscriber specified in the call has a status of Returned (Held) or Unsubscribed,

the send will be aborted. In this case, you will not receive a confirmation message.

Additional

Info:

The single-send option is a special API feature. The results of this email send will be

contained in the Tracking section of the ExactTarget application under My

Tracking\Single Send Emails. Tracking results will be retained in the system for 30 days.

The email that you send has all the same features as a mass email: personalized content,

reply mail management (if you have this advanced feature enabled in your account),


73

surveys, and so on.

See also Job Send (Mass Email), to send an email to a list or group.

Method

To send an email from your ExactTarget account to a single subscriber, use the following syntax:

<system>

<system_name>job</system_name>

<action>send_single</action>



<search_value2>1001992233</search_value2>

<from_name></from_name>

<from_email></from_email>

</system>


<search_value> The email ID of the email that you want to send.

<search_value2> The subscriber ID of the subscriber to whom you are sending the email.

<from_name> and

<from_email>

If you have the advanced multiple-From option enabled in your account, enter

the From name and email address to display on this email. If you do not have

this option enabled, leave the values for these tags blank (the Email Display

Name and Email From Address defined in your account settings will be used).

If you're using the Enterprise version of the application and you're sending this

email for an On Your Behalf (Dynamic One-to-One) channel member, enter

@@ChannelMemberDisplayName@@ as the <from_name> value and

@@ChannelMemberEmail@@ as the <from_email> value.

Results

The successful completion of this script will return the job ID in the <job_description field>, which you can

subsequently use to identify this email send.


<exacttarget>

<system>

<job>

<job_info>Job was successfully created.</job_info>

<job_description>2030602</job_description>

</job>

</system>

</exacttarget>


to be implemented.


74




75

Tracking (Event Data Requests)

Introduction to Tracking (Event Data Requests)

After sending out an email campaign, you can extract the campaign's tracking data from the ExactTarget

application, in bulk or for a specific subscriber. You can use these API calls to query the ExactTarget

system at any time after the email send.

Tracking Retrieve Job IDs


Purpose: Retrieve all job IDs for emails sent during a specified period.

Input: Start date and/or end date. (You also have the option of not specifying a date range, to

return all job IDs in your account.)

Results: The job IDs, along with the send date and list IDs used in the jobs, are returned to you.

Additional

Info:

None.

Method

To retrieve job IDs, use the following syntax. Note that the use of a date range, shown in this code sample,

is optional. You can specify no dates to return all job IDs, or specify just a start date or just an end date for

an open-ended date range.

<system>


<action>jobretrieve</action>

<sub_action>jobs</sub_action>


<search_value>9/15/2005 10:30:00AM</search_value>


</system>


<search_value> (Optional) Enter the start date and time in the format M/D/YYYY H:M:S AM

or PM.

To return all job IDs in your account, leave both the start date and end date

blank.


76

For an open-ended date range, leave one blank. (If you enter a value for

<search_value> and leave <enddate> blank, job IDs for all emails sent after the

start date will be returned, and vice-versa.)

<search_value2> (Optional) Enter the end date and time in the format M/D/YYYY H:M:S AM

or PM.

Results



<exacttarget>

<system>

<tracking>

<jobs>

<job>

<jobID>2030420</jobID>

<jobSendDate>9/29/2005 9:42:00

AM</jobSendDate>

<lists>


</lists>

</job>

<job>


<jobSendDate>9/29/2005 9:50:00

AM</jobSendDate>

<lists>


</lists>

</job>

<job>


<jobSendDate>9/29/2005 10:14:00

AM</jobSendDate>

<lists>


</lists>

</job>

</jobs>

</tracking>

</system>

</exacttarget>


to be implemented.


77



Tracking Retrieve Summary


Purpose: Retrieve summarized tracking data for an email send, in XML format.

Input: Job ID or event ID.

Results: Details of the email's results are returned to you.

Additional

Info:

See also Tracking Retrieve (Bulk Export), which gives you complete tracking data.

Method

To retrieve tracking data for an email send, use the following syntax:

<system>



<sub_action>summary</sub_action>




</system>

If the additional information functionality is enabled in your account, you can substitute eventid as the

<search_type> and enter the event ID as the <search_value> value.


<search_value> Job ID of the email send for which you want to retrieve tracking data.

If the additional information functionality is enabled in your account, you can

enter the event ID as the value for this tag (change the <search_type> to

eventid).


Results

The successful completion of this script will return the tracking data for the email send. Here's an example:


78


<exacttarget>

<system>

<tracking>

<emailSummary>

<EmailName>Intro Email</EmailName>

<EmailSubject>Introduction to Fortune

One</EmailSubject>

<FromName>Fortune One</FromName>

<FromEmail>[email protected]</FromEmail>

<Additional />

<IsMultipart>False</IsMultipart>

<DeliveredTime>8/10/2005 11:30:00

AM</DeliveredTime>

<Lists>

<list>

<list_ID>553042</list_ID>

<list_name>premier email

list</list_name>

</list>

</Lists>

<sentCount>163</sentCount>

<deliveredCount>163</deliveredCount>

<undeliveredCount>0</undeliveredCount>

<unSubscribedCount>0</unSubscribedCount>

<openCount>145</openCount>

<uniqueClickCount>18</uniqueClickCount>

<SurveyResponseCount>35</SurveyResponseCount>

<FTAF_summary>




</FTAF_summary>

<email_links>

<link>

<URL>http://cl.exct.net/profile_cente

r.aspx?s=%%ex2; subscriberid%%</URL>

<name>Update Profile</name>

<click_throughs>0</click_throughs>

<Percent>0.0%</Percent>

<Net_CTR>0.0%</Net_CTR>

</link>

<link>

<URL>http://cl.exct.net/subscription_

center.aspx?s=%%ex2;

subscriberid%%&j=fe9c157675620578

75</URL>

<name>Manage Subscriptions</name>



79



</link>

<link>

<URL>http://cl.exct.net/unsub_center.

aspx?s=%%ex2;

subscriberid%%&j=fe9c157675620578

75</URL>

<name>Unsubscribe</name>




</link>

</email_links>

<Conversion_Summary />

</emailSummary>

</tracking>

</system>

</exacttarget>


to be implemented.



Tracking Retrieve (Bulk Export)


Purpose: Retrieve complete tracking data for an email send, in XML format.

Input: Job ID or event ID.

Results: Details of the email's results are returned to you.

Additional

Info:

Three variations of this method are available, depending on how much detail you want to

retrieve:

� Complete tracking data;

� Complete tracking data with the addition of subscriber attributes; and

� Either of the preceding two variations with the restriction of a date range.

Note: Information for a subscriber is included only if the email to that subscriber was

opened, returned, or found to be undeliverable.

See also Tracking Retrieve Summary, which retrieves a summary of the tracking data;


80

Tracking Retrieve Single Subscriber, which retrieves tracking data for a specified

subscriber; and Tracking Bulk Async, which is the batch file export version of the

Tracking Retrieve (Bulk Export) call.

Method

To retrieve complete tracking data for an email send, use the following syntax. Note that the use of a date

range, shown in this code sample, is optional.

<system>







<daterange>



</daterange>

</system>

If you want to include the attribute data for each subscriber involved in this email send, use the following

syntax. Note that this sample does not show the date range option, which can be added (follow the syntax

shown above).

<system>



<sub_action>all_attributes</sub_action>




</system>

If the additional information functionality is enabled in your account, you can substitute eventid as the

<search_type> and enter the event ID as the <search_value> value.



If the additional information functionality is enabled in your account, you can

enter the event ID as the value for this tag (change the <search_type> to

eventid).


<daterange> (Optional) If you want to retrieve tracking data for a specific period, enter the

dates within the <startdate> and <enddate> tags in the format M/D/YYYY.


81

Results

The successful completion of this script will return the tracking data for the email send.


to be implemented.

An explanation of the subscriber data returned appears at the end of this topic.

Action: All

Here's an example of results without the subscriber attributes:


<exacttarget>

<system>

<tracking>

<emailSummary>

<EmailName>test</EmailName>

<EmailSubject>test</EmailSubject>

<FromName>Fortune One Test</FromName>

<FromEmail>[email protected]</FromEmail>

<Additional/>

<IsMultipart>True</IsMultipart>

<DeliveredTime>2/18/2004 12:24:00

PM</DeliveredTime>

<Lists>

<list>

<list_ID>116723</list_ID>

<list_name>demo</list_name>

</list>

</Lists>

<sentCount>7</sentCount>

<deliveredCount>7</deliveredCount>

<undeliveredCount>0</undeliveredCount>

<unSubscribedCount>2</unSubscribedCount>

<openCount>7</openCount>

<uniqueClickCount>4</uniqueClickCount>

<FTAF_summary>




</FTAF_summary>

<email_links>

<link>

<URL>http://brochuresite.exacttarget.

com/policies/ anti_spam.asp</URL>

<name></name>




82


</link>

</email_links>

<Conversion_Summary />

</emailSummary>

<subscribers>

<subscriber>



<firstname>D.</firstname>

<lastname>Smith</lastname>


<type>HTML</type>

<status>Active</status>

<undeliverable />

<opens />

<clicks>

<clickdate>7/26/2005 10:36:00

AM</clickdate>

<clickUrl><![CDATA[http://cl.exct.net/prof

ile_center.aspx? s=%%ex2;

subscriberid%%]]></clickUrl>

</clicks>

<unsubscribe />

<surveyResponses />

<conversions />

</subscriber>

<subscriber>



<firstname>

</firstname>

<lastname>

</lastname>


<type>TEXT</type>

<status>Returned</status>

<undeliverable>

<undeliverableDate>7/26/2005 10:40:00

AM</undeliverableDate>

</undeliverable>

<opens />

<clicks />

<unsubscribe />

<surveyResponses />

<conversions />

</subscriber>

</subscribers>

</tracking>


83

</system>

</exacttarget>

Action: All_Attributes

Here's a snippet of an example with the subscriber attributes included. Only the <subscribers> section

differs from the example above.

<subscribers>

<subscriber>






<type>HTML</type>


<Indianapolis__Metro__Region>Hamilton

County</Indianapolis__Metro__Region>

<Weekly__Survey__Email>False</Weekly__Surv

ey__Email>

<Greeting>Hello</Greeting>

<Money__Spent__This__Fiscal__Year>1000</Mo

ney__Spent__This __Fiscal__Year>

<City>Fishers</City>

<List />

<Catalog__Preference>False</Catalog__Prefe

rence>

<undeliverable />

<opens />

<clicks>

<clickdate>7/26/2005 10:36:00

AM</clickdate>


ile_center.aspx?

s=%%ex2;subscriberid%%]]></clickUrl>

</clicks>

<unsubscribe />

<surveyResponses />

<conversions />

</subscriber>

<subscriber>



<firstname>Leona</firstname>

<lastname>Damon</lastname>


<type>TEXT</type>

<status>Returned</status>


84

<Indianapolis__Metro__Region>Marion

County</Indianapolis__Metro__Region>

<Weekly__Survey__Email>False</Weekly__Surv

ey__Email>

<Greeting>Dear</Greeting>

<Money__Spent__This__Fiscal__Year>0</Money

__Spent__ This__Fiscal__Year>

<City>Lawrence</City>

<List />

<Catalog__Preference>False</Catalog__Prefe

rence>

<undeliverable>

<undeliverableDate>7/26/2005 10:40:00

AM</undeliverableDate>

</undeliverable>

<opens />

<clicks />

<unsubscribe />

<surveyResponses />

<conversions />

</subscriber>

</subscribers>

Subscriber Data Explanation

The follow table explains the key tracking data contained in the <subscribers> section of the results.

Data Explanation

<subscriberID> The unique ID of this subscriber.

<list ID> The unique ID of the list selected for this email send to which the subscriber

belongs.

Attribute data A tag exists for each profile and preference attribute defined in your account. If

any data has been entered for the subscriber in that attribute, the data appears

between the tags.

<status> The subscriber's status: Active, Unsubscribed, Returned, or Undeliverable.

Please refer to the application online help for an explanation of subscriber

status.

<undeliverable> If the email was undeliverable, this tag contains the date and time that the

email was returned to ExactTarget.

Having both an <undeliverable> date and an <opens> date is not uncommon,

as ExactTarget makes three send attempts. If the second or third attempt was

successful, you may see the date and time of the undeliverable attempt and

then the date and time when the subscriber was able to open the email.


85

<opens> If the subscriber opened the email, this tag contains the date and time that the

email was opened. (All open events are captured; if the subscriber opened the

email multiple times, you'll see multiple dates and times.)

<clicks> For each link in the email that the subscriber clicked, this section consists of a

<clickdate> tag containing the click date and time and a <clickUrl> tag

containing the URL wrapped in a CDATA tag.

<unsubscribe> If the subscriber unsubscribed, this tag contains the date and time when the

unsubscribe occurred. An unsubscribe occurs when the subscriber chooses to

unsubscribe via the links provided in the email, through the Reply Mail

Management process (if you have this advanced feature enabled in your

account), or through the subscriber clicking the Report as Spam button in

America Online (AOL).

<surveyResponses> If the email contained a survey and the subscriber responded, this tag contains

the subscriber's responses.

<conversions> If the advanced conversion tracking feature is enabled in your account, this

section shows the click-through results for all links marked for conversion

tracking in the email.



Tracking Retrieve Single Subscriber

Tracking Retrieve Summary

Tracking Bulk Async

Tracking Retrieve Single Subscriber


Purpose: Retrieve a single subscriber's tracking data for an email send, in XML format.

Input: Job ID and subscriber ID.

Results: Details of the subscriber's activity with the email send are returned to you.

Additional

Info:

See also Tracking Retrieve (Bulk Export), which returns all subscribers' tracking data.

Method

To retrieve a single subscriber's tracking data for an email send, use the following syntax:


86

<system>



<sub_action>single</sub_action>



<search_value2>300400108</search_value2>

</system>



<search_value2> Subscriber ID of the subscriber whose tracking data you want to retrieve.

Results

The successful completion of this script will return the subscriber's tracking data for the email send. See

Tracking Retrieve (Bulk Export) for an explanation of the elements in this output.


<exacttarget>

<system>

<tracking>

<subscribers>

<subscriber>






<type>HTML</type>


<undeliverable />

<opens />

<clicks>

<clickdate>7/26/2005 10:36:00

AM</clickdate>


ile_center.aspx? s=%%ex2;

subscriberid%%]]></clickUrl>

</clicks>

<unsubscribe />

<surveyResponses />

<conversions />

</subscriber>

<subscribers>

</tracking>

</system>


87

</exacttarget>


to be implemented.



Tracking Retrieve Unsubscribes


Purpose: Retrieve the subscribers in your account (and your subaccounts, if any) who

unsubscribed during a specified period.

Input: Date range.

Results: Profile and preference attribute data and unsubscribe date for the unsubscribed

subscribers are returned to you.

Additional

Info:

Unsubscribes are retrieved from your current lists only. Unsubscribe info cannot be

retrieved from deleted subscriber lists. If the subscriber has been deleted from the list,

only the email address and date information will be returned.

Method

To retrieve your unsubscribed subscribers, use the following syntax:

<system>

<system_name>tracking-channel</system_name>


<sub_action>unsubscribe</sub_action>


<search_value>9/1/2005</search_value>

<search_value2>12/31/2005</search_value2>

</system>


<search_value> Start date of the reporting period, in the format M/D/YYYY.

<search_value2> End date of the reporting period, in the format M/D/YYYY.


88

Results

The successful completion of this script will return the unsubscribe date and attribute data for all

unsubscribes during the specified period.


<exacttarget>

<system>

<tracking>

<subscribers>

<subscriber>

<date>12/22/2002 2:18:00 PM</date>

<Full__Name>James Guidry</Full__Name>

<Email__Address>[email protected]</Email_

_Address>

<Status>unsub</Status>


<Interest>Barbecue</Interest>

</subscriber>

<subscriber>

<date>12/25/2002 3:49:00 PM</date>

<Full__Name>Elizabeth Young</Full__Name>

<Email__Address>[email protected]</Email_

_Address>

<Status>unsub</Status>


<Interest>Camping</Interest>

</subscriber>

<subscribers>

</tracking>

</system>

</exacttarget>


to be implemented.




89

Image Management

Introduction to Image Management

With an API call, you can upload multiple image files at once into your ExactTarget account, using the

ExactTarget FTP site. (See the FTP Instruction Guide PDF.)

Image Import (Upload Trigger)


Purpose: Upload image files to your ExactTarget image library.

Input: Filename(s).

Results: A confirmation message, including the total number of files uploaded and the new

system-generated filenames of the images, is returned to you.

Additional

Info:

The first part of the import process is to upload your image files to the ExactTarget FTP

site. Please refer to the online help within the ExactTarget application for details on

image requirements.

You may import as many as 25 images at a time. The size of your entire image library is

limited to 100MB; for best results, each of your images should be no larger than 200K.

Your images will be added to the My Images folder of your ExactTarget application.

Method


Upload your image file or files by dragging and dropping them at the FTP site:


To import the files into your ExactTarget My Images folder, use the following syntax:

<system>

<system_name>filemanagement</system_name>

<action>filemove</action>

<source>

<location>ExactTargetFTP</location>

<files

<filename>20502Logo1.jpg</filename>

<filename>20502LogoSmall.jpg</filename>

</files>


90

</source>

</system>


<filename> The name of the image file to be uploaded. For each file that you're uploading,

create a separate tag.

Results

The successful completion of this script will return output similar to the following. Note the following:

� Each <filemanagement-filename> tag contains the system-generated filename that the application

will use to identify the file. If you now want to use these files in an email, specify the system-

generated filenames.

� The <filemanagement-filesmoved> tag at the end of the output indicates how many files were

successfully uploaded.


<exacttarget>

<system>

<filemanagement>

<filemanagement-file>

<filemanagement-

filename>3611148524319.jpg</filemanagement-

filename>

<filemanagement-info>Moved</filemanagement-

info>

</filemanagement-file>

</filemanagement>

<filemanagement>


<filemanagement-

filename>35623314819.jpg</filemanagement-

filename>

<filemanagement-info>Moved</filemanagement-

info>


<filemanagement-filesmoved>2</filemanagement-

filesmoved>

</filemanagement>

</system>

</exacttarget>

If a filename specified in your API call is not found on the FTP site, the <filemanagement-info> tag for that

file will so indicate:


<filemanagement-

filename>20502Logo1.jpg</filemanagement-

filename>


91

<filemanagement-info>file did not

exist</filemanagement-info>



to be implemented.




93

API Application Code Samples


94

Introduction to Application Code Samples

This section provides Visual Basic and ASP examples showing how you can integrate with the ExactTarget

API. Please note that some line wrapping may have occurred in order to display these samples within the

help page. Do not copy and paste these code examples from this documentation into your own code; doing

so will typically result in unusable code, due to the line breaks created by formatting the code for use in this

documentation.

If you'd like to receive the ASP examples in their native ASP format, or any of the other examples in a

usable format, contact ExactTarget.

Note: These examples are for demonstration purposes only. ExactTarget makes no warranties in regards to

these samples and is not responsible for actions caused by the use of this code in your production

environment.


95

Visual Basic Example

Note: Do not copy and paste these code examples from this documentation into your own code; doing so

will typically result in unusable code, due to the line breaks created by formatting the code for use in this

documentation.

Here's an example of how you can build a Visual Basic project to integrate with the ExactTarget API:

1. Create a new project in VB. Ensure that Microsoft XML, v4.0 is included as a reference in the list

of project references.

2. Create a new form having the following elements on it:

Element Type Name Purpose

Textbox txtUserName ExactTarget user ID.

Textbox txtPassword ExactTarget password.

Textbox txtSystem System specified in the API call you're making (for

example, tracking).

Textbox txtAction Action specified in the API call you're making (for

example, retrieve).

Textbox txtSubAction Sub_action, if any, specified for the API call you're

making (for example, single).

Textbox txtSearchType Search_type specified for the API call you're making

(for example, jobid).

Textbox txtSearchValue Search_value specified for the API call you're making

(for example, the job ID).

Textbox txtSearchValue2 Search_value2, if any, specified for the API call you're

making (for example, the subscriber ID).

Textbox txtResults Text box to contain the output of your call.

CommandButton cmdExecute Button to run the routine.

3. In the Click event of the cmdExecute command button, use the following code:

Dim xmlDoc As DOMDocument

Dim oNodeListData As IXMLDOMNodeList

Dim currNode As IXMLDOMNode

Dim bParseData As Boolean

Dim sURLString As String

Dim sCategory As String

Dim iNodeCount As Integer


96

Set xmlDoc = New DOMDocument

‘If you are using the XML based call, this is the code example

to reference

strXML = "<?xml version=""1.0"" ?>" & _

"<exacttarget>" & _

"<authorization>" & _

"<username>" & Me.txtUserName.text & "</username>" & _

"<password>" & Me.txtpassword.text& "</password>" & _

"</authorization>" & _

"<system>" & _

"<system_name>” & Me.txtSystem.Text &”</system_name>" &

_

"<action>” & Me.txtAction.Text & “</action>" & _

"<sub_action> &Me. txtSubAction. Text & “</sub_action>”

&_

"<search_type>” & Me.SearchType.text & “</search_type>"

& _

"<search_value>” & Me.searchValue.text</search_value>"

& _

"<search_value2>” &

Me.searchValue2.text</search_value2>" & _

"</system>" & _

"</exacttarget>"

sURLString =

"https://www.exacttarget.com/api/integrate.asp?qf=xml&xml=" &

strXML

‘ If you are using Named Value Pair, this is the code example to

reference

sURLString =

"https://www.exacttarget.com/api/integrate.asp?qf=nvp" _

& "&username=" & Me.txtUserName.Text _

& "&password=" & Me.txtPassword.Text _

& "&system=" & Me.txtSystem.Text _

& "&action=" & Me.txtAction.Text _

& "&sub_action=" & Me.txtSubAction.Text _

& "&search_type=" & Me.txtSearchType.Text _

& "&search_value=" & Me.txtSearchValue.Text _

& "&search_value2=" & Me.txtSearchValue2.Text

xmlDoc.async = False

xmlDoc.Load sURLString

'loop through the email summary items and display the results in

a text box

sCategory = "emailSummary"

If xmlDoc.getElementsByTagName(sCategory).length > 0 Then

Set oNodeListData =

xmlDoc.getElementsByTagName(sCategory).Item(0).childNodes


97

For iNodeCount = 1 To oNodeListData.length

Me.txtResults.Text = Me.txtResults.Text &

oNodeListData.Item(iNodeCount -1).nodeName & ": " &

oNodeListData.Item(iNodeCount - 1).Text & vbNewLine

Next iNodeCount

End If

4. Run the program and fill in the text boxes using valid ExactTarget values for each field (refer to

the API call documentation). Click the Execute button to see the results.


98

ASP Example: Add List



documentation.

This example shows an ASP page adding a subscriber list to your ExactTarget account. This example uses

the Microsoft XML Parser version 3.04.

<HTML>

<HEAD>

<META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0">

</HEAD>

<BODY>

<P>

<%

'*******************************************************************

*****************

'* DISCLAIMER

'* Each of these code samples is provided as is and is not

warrantied. These samples

'* are provided for our customers to see an example API call and

understand how they

'* can utilize this API for use in integrating with their own

applications.

'* This example was created using the MSXML 3.04 Parser. Please be

sure to download

'* the latest service pack for MSXML 3.0.

'*******************************************************************

*****************

' Dim all variables

Dim objSXH

Dim objXML

Dim strURL

Dim strXML

Dim objXMLDOM

Dim strCategory

Dim intChildNodeCount

Dim intNodeCount

Dim strNodeName

Dim objNodeList

Dim objChildNode

Dim objChildren

Dim intCnt1

Dim intCnt2

' Create the XML String

'substitute your username and password where you see USERNAME and

PASSWORD


99

strXML = "<?xml version=" &chr(34) &"1.0"& chr(34)&

"?><exacttarget><authorization>"_

&"<username>USERNAME</username>"_

&"<password>PASSWORD</password></authorization><system>"_

&"<system_name>list</system_name>"_

&"<action>add</action>"_

&"<search_type></search_type>"_

&"<search_value></search_value>"_

&"<list_name>next new list</list_name>"_

&"</system></exacttarget>"

' Create the full URL

strUrl = "http://www.exacttarget.com/api/integrate.asp"

' Create the HTTP Object

Set objSXH = server.CreateObject("msxml2.ServerXMLHttp.3.0")

objSXH.open "POST", strUrl,false

' Post the XML body

objSXH.setRequestHeader "Content-Type","application/x-www-form-

urlencoded"

objSXH.send ("qf=xml&xml=" & Server.URLEncode(strXML))

' This step if there is is no error will begin to parse the response

from ExactTarget

If ObjSXH.status = 200 Then

'Create the MSXML Document Object from the response stream

Set ObjXML = ObjSXH.responseXML

'if you want to save the file, you can use this to do so

'objXML.Save(Server.MapPath("listadd.xml"))

' Get the first subscriber in the XML Doc and get the list info

' Node names are case sensitive

set objNodeList = objXML.GetElementsByTagName("list")

intNodeCount = objNodeList.length

'if no nodes, then there was an error

if intNodeCount = 0 then

response.write objSXH.responsexml.xml

Else

' this loop will work through each subscriber node

for intCnt1 = 0 to (intNodeCount - 1)

set objChildnode = objNodeList.item(intCnt1)


100

set objChildren = objChildnode.childnodes

' this loop will work through all child nodes within the

subscriber node

for intCnt2= 0 to (objChildren.length - 1)

response.write "Node Name: " & "<b>" &

objChildren.item(intCnt2).nodename & "</b>" & " Value:

" &"<b>"& objChildren.item(intCnt2).text & "</b><br>"

' if you need to perform a comparison you can use a select

' case statement to obtain a specific values or set of

values

next

response.write "</p>"

next

end if

Else

Response.Write "An error occurred." & objSXH.responsexml.xml

Response.write "Status " & objSXH.status & "<br>"

Response.write "Status text " & objSXH.statustext

end if

'Clean up objects and remove them from memory

set objChildren = Nothing

set objChildnode = Nothing

set objNodeList = Nothing

Set ObjXML = Nothing

Set ObjSXH = Nothing

%>

</P>

</BODY>

</HTML>


101

ASP Example: Retrieve Tracking Data



documentation.



<HTML>

<HEAD>


</HEAD>

<BODY>

<P>

<%

'*******************************************************************

*****************

'* DISCLAIMER




understand how they


applications.


sure to download


'*******************************************************************

*****************

' Dim all variables

Dim objSXH

Dim objXML

Dim strURL

Dim strXML

Dim objXMLDOM

Dim strCategory


Dim intNodeCount

Dim strNodeName

Dim objNodeList

Dim objChildNode

Dim objChildren

Dim intCnt1

Dim intCnt2


'substitute your username and password where you see USERNAME and

PASSWORD


102


"?><exacttarget><authorization>"_

&"<username>USERNAME</username>"_

&"<password>PASSWORD</password></authorization><system>"_

&"<system_name>tracking</system_name>"_

&"<action>retrieve</action>"_

&"<sub_action>all_attributes</sub_action>"_

&"<search_type>jobID</search_type>"_

&"<search_value>272637</search_value>"_

&"<search_value2></search_value2></system></exacttarget>"






' Post the XML body


urlencoded"



from ExactTarget





'objXML.Save(Server.MapPath("bulkexport.xml"))

' Get the first subscriber in the XML Doc and get the number


set objNodeList = objXML.GetElementsByTagName("subscriber")





Else






103


subscriber node



objChildren.item(intCnt2).nodename & "</b>" & " Value: "

&"<b>"& objChildren.item(intCnt2).text & "</b><br>"

' if you need to perform a comparison you can use a select


values

next


next

end if

Else

Response.Write "An error occurred."



end if







%>

</P>

</BODY>

</HTML>


104

ASP Example: Add HTML Paste Email



documentation.



<HTML>

<HEAD>


</HEAD>

<BODY>

<P>

<%

'*******************************************************************

*****************

'* DISCLAIMER




understand how they


applications.


sure to download


'*******************************************************************

*****************

' Dim all variables

Dim objSXH

Dim objXML

Dim strURL

Dim strXML

Dim objXMLDOM

Dim strCategory


Dim intNodeCount

Dim strNodeName

Dim objNodeList

Dim objChildNode

Dim objChildren

Dim intCnt1

Dim intCnt2



105

' substitute your username and password where you see USERNAME and

PASSWORD

' note: %26 is used in place of & in URLs and %25 is used for a %

symbol

' in tags such as width = "100%"


"?><exacttarget><authorization><username>USERNAME</username>"_

&"<password>PASSWORD</password></authorization><system><system_name>

email </system_name>"_

&"<action>add</action><sub_action>HTMLPaste</sub_action><search_type

/><search_value />"_

&"<category></category><email_name>Northern Trails HTML

Email</email_name><email_subject>Northern Trail

Specials</email_subject>"_

&"<email_body><![CDATA["_

&"<body><body bgcolor="& chr(34) & "#ffffff"& chr(34) & " text= "&

chr(34) &"#000000"& chr(34) & ">"_

&"<custom name=" &chr(34) & "opencounter" &chr(34)& " type=" &

chr(34) & "tracking"& chr(34) & " ><center>"_

&"<table width=" & chr(34) & "600" & chr(34) & " height=" & chr(34)

& "400" & chr(34)_

&"cellpadding=" & chr(34) & "0 "& chr(34) & " cellspacing="& chr(34)

& "0"& chr(34)_

& " bordercolor="& chr(34) & "#000000"& chr(34)_

&" border="& chr(34) & "1"& chr(34) & " bgcolor="& chr(34) &

"#EFEFDE"& chr(34) & ">"_

&"<tr height=" & chr(34) & "50"& chr(34) & " bgcolor="& chr(34) &

"#FFFFFF"& chr(34) & "><td valign="_

& chr(34) & "middle"& chr(34) & " width="& chr(34) & "100%25"&

chr(34) & " align="& chr(34)_

& "center"& chr(34) & "><img

src='https://www.exacttarget.com/members/images/484265907055475.jpg'

border="& chr(34)_

& "0"& chr(34) & "></td>"_

&"</tr><tr><td valign="& chr(34) & "top"& chr(34) & " colspan="&

chr(34) & "2"_

& chr(34) & " width="& chr(34) & "100%25"& chr(34) & "><table

cellpadding="& chr(34)_

& "12"& chr(34) & " cellspacing="& chr(34) & "0"& chr(34) & "

border="& chr(34)_

& "0"& chr(34) & " width="& chr(34) & "100%25"& chr(34) & "

height="& chr(34)_

& "100%25"& chr(34) & "> <tr>"_

&" <td height="& chr(34) & "16%25"& chr(34) & " width="& chr(34) &

"33%25"_

& chr(34) & " valign="& chr(34) & "top"& chr(34) & "><table



border="& chr(34)_


106

& "1"& chr(34) & " bordercolor="& chr(34) & "CCCCCC"& chr(34) & "

width="& chr(34)_

& "100%25"& chr(34) & " height="& chr(34) & "100%25"& chr(34) & "

bgcolor="_

& chr(34) & "#ffffff"& chr(34) & ">"_

&"<tr><td align="& chr(34) & "center"& chr(34) & "><table



border="& chr(34)_

& "0"& chr(34) & "><tr><td align="& chr(34) & "center"& chr(34) &

"><custom name="_

& chr(34) & "pictureholder"& chr(34) & " type="& chr(34) &

"pictureholder"& chr(34)_

& "><img

src='https://www.exacttarget.com/members/images/33925507055475.jpg'>

</custom name="_

& chr(34) & "pictureholder"& chr(34) & "></td></tr><tr><td>"_

&"<P><FONT face=Verdana size=2><STRONG><FONT face=Arial></FONT><A

name=top><FONT face=Verdana size=2>"_

&"<STRONG></STRONG></FONT></A><FONT

face=Arial></FONT><BR></STRONG><BR>Our "& chr(34)_

& "Mountain Jacket"& chr(34) & " keeps you comfortable from base to

peak and everything in between."_

&" You can't beat it at our special price! <A

href='http://www.exacttarget.com'>Click for more details.</A>"_

&"</FONT></P></td></tr></table></td></tr></table></td>"_

&"<td height="& chr(34) & "16%25"& chr(34) & " width="& chr(34) &

"66%25"& chr(34)_

& " valign="& chr(34) & "top"& chr(34) & "><table cellpadding="&

chr(34) & "4"& chr(34)_

& " cellspacing="& chr(34) & "0"& chr(34) & " border="& chr(34) &

"0"& chr(34) & " width="_

& chr(34) & "100%25"& chr(34) & " height="& chr(34) & "100%25"&

chr(34) & "><tr><td valign="_

& chr(34) & "top"& chr(34) & " style="& chr(34) & "border-

style:dashed; border-color: #CCCCCC;"_

& chr(34) & "><FONT face=Verdana size=2>Dear

%%fullname%%,</FONT></P>"_

&"<P align=left><FONT face=Verdana size=2>At NorthernTrail

Outfitters, we supply everything you"_

&" need for your adventure needs. We offer kayaks, outerwear,

boating equipment, travel getaways"_

&" and much more. This email will provide you with some of our

feature <A href='http://www.exacttarget.com/'>"_

&"products </A>and travel destinations that we have to

offer.</FONT></P>"_

&"<P align=left><FONT face=Verdana size=2>At NorthernTrail

Outfitters, we supply everything you"_

&" need for your adventure needs. We offer kayaks, outerwear,

boating equipment, travel getaways"_

&" and much more. This email will provide you with some of our

feature <A href='http://www.exacttarget.com/'>"_


107

&"products </A>and travel destinations that we have to

offer.</FONT></P>"_

&"<TABLE cellpadding="& chr(34) & "4"& chr(34) & " cellspacing="&

chr(34) & "0"& chr(34)_

& " border="& chr(34) & "0"& chr(34) & " width="& chr(34) &

"100%25"& chr(34) & " height="& chr(34)_

& "100%25"& chr(34) & " ><TR><TD valign="& chr(34) & "top"& chr(34)

& "><TR><TD align="& chr(34)_

& "left"& chr(34) & "> <TABLE cellpadding="& chr(34) & "4"& chr(34)

& " cellspacing="& chr(34)_

& "0"& chr(34) & " border="& chr(34) & "0"& chr(34) & " width="&

chr(34) & "100%25"& chr(34)_

& " height="& chr(34) & "100%25"& chr(34) & " bgcolor="& chr(34) &

"efefde"& chr(34) & ">"_

&"<TR><TD valign="& chr(34) & "top"& chr(34) & "><custom name="&

chr(34) & "pictureholder"& chr(34)_

& " type="& chr(34) & "pictureholder"& chr(34) & "><TABLE

cellspacing="& chr(34) & "0"& chr(34)_

& " cellpadding="& chr(34) & "0"& chr(34) & " align="& chr(34) &

"right"& chr(34) & "><TR><TD align="_

& chr(34) & "left"& chr(34) & " width="& chr(34) & "600"& chr(34) &

"></TD></TR></TABLE></TD></TR></TABLE></td>"_

&"</tr><tr><td width="& chr(34) & "100%25"& chr(34) & " height="&

chr(34) & "16%25"& chr(34)_

& " colspan="& chr(34) & "2"& chr(34) & " valign="& chr(34) & "top"&

chr(34) & "><table cellpadding="_

& chr(34) & "0"& chr(34) & " cellspacing="& chr(34) & "0"& chr(34) &

" border="& chr(34) & "0"& chr(34)_

& " width="& chr(34) & "100%25"& chr(34) & " height="& chr(34) &

"100%25"& chr(34) & "><tr><td align="_

& chr(34) & "center"& chr(34) & "><table cellpadding="& chr(34) &

"0"& chr(34) & " cellspacing="& chr(34)_

& "0"& chr(34) & " border="& chr(34) & "0"& chr(34) & ">"_

&"<tr><td align="& chr(34) & "center"& chr(34) & ">

</td></tr><tr><td><P><FONT face=Verdana size=2>Staying"_

&" comfortable in the wild makes all the difference. Choose from any

of our latest lightweight designs, all in"_

&" waterproof, rip-stopping nylon. New technology incorporated here

means you'll have your tent up quicker than ever."_

&" <A href='http://www.exacttarget.com'>Find the right tent for

you!</A></FONT></P></td></tr></table></td></tr></table></td>"_

&"</tr><tr><td width="& chr(34) & "1002%"& chr(34) & " height="&

chr(34) & "16%25"& chr(34) & " colspan="& chr(34)_

& "2"& chr(34) & " valign="& chr(34) & "top"& chr(34) & "><table

cellpadding="& chr(34) & "4"& chr(34)_


"0"& chr(34) & " width="& chr(34)_

& "100%25"& chr(34) & " height="& chr(34) & "100%25"& chr(34) &

"><tr><td valign="& chr(34) & "top"& chr(34)_

& " align="& chr(34) & "center"& chr(34) & "><img

src='https://www.exacttarget.com/members/images/27812707055475.jpg'>

"_


108

&"</td></tr></table></td>"_


chr(34) & "16%25"& chr(34) & " colspan="_

& chr(34) & "2"& chr(34) & " valign="& chr(34) & "top"& chr(34) &

"></td></tr><tr>"_

&"<td width="& chr(34) & "100%25"& chr(34) & " height="& chr(34) &

"16%25"& chr(34) & " colspan="& chr(34)_

& "2"& chr(34) & " valign="& chr(34) & "top"& chr(34) & "> <table

cellpadding="& chr(34) & "4"& chr(34)_


"0"& chr(34) & " width="& chr(34)_

& "100%25"& chr(34) & " height="& chr(34) & "100%25"& chr(34) & "

><tr>"_

&"<td valign="& chr(34) & "top"& chr(34) & "><hr line="& chr(34) &

"100%25"& chr(34)_

& "><P align=center><FONT face=Arial size=2><FONT

color=#636363>NorthernTrail Outfitters - 3457"_

&" Hargrove St. - Walker, MN - 612-555-9879</FONT>

</FONT></P></td></tr></table> </td>"_


chr(34) & "16%25"& chr(34)_

& " colspan="& chr(34) & "2"& chr(34) & " valign="& chr(34) & "top"&

chr(34) & "></td></tr>"_

&"</table></td></tr></table>Go <a

href='%25%25account_info_url%25%25'>here</a> to"_

&" leave this mailing list or <a

href='%25%25account_info_url%25%25'>modify</a> your email profile."_

&"<table cellpadding="& chr(34) & "2"& chr(34) & " cellspacing="&

chr(34) & "0"& chr(34) & " width="_

& chr(34) & "600"& chr(34) & " ID="& chr(34) & "Table5"& chr(34) & "

Border=0>"_

&"<tr><td><font face="& chr(34) & "verdana"& chr(34) & " size="&

chr(34) & "1"& chr(34) & " color="_

& chr(34) & "#444444"& chr(34) & ">This email was sent by:

<b>%25%25Member_Busname%25%25</b><br>%25%25Member_Addr%25%25"_

&" %25%25Member_City%25%25, %25%25Member_State%25%25,

%25%25Member_PostalCode%25%25,

%25%25Member_Country%25%25<br><br></td></tr></table></center></body>

"_

&"]]></email_body></system></exacttarget>"






' Post the XML body


urlencoded"


109



from ExactTarget





'objXML.Save(Server.MapPath("emailadd.xml"))

' Get the first subscriber in the XML Doc and get the list info


set objNodeList = objXML.GetElementsByTagName("email")





Else






subscriber node



objChildren.item(intCnt2).nodename & "</b>" & " Value: "

&"<b>"& objChildren.item(intCnt2).text & "</b><br>"

' if you needed to perform a comparison you could either use

a select


values

next


next

end if

Else

Response.Write "An error occurred."



110


end if







%>

</P>

</BODY>

</HTML>

111

API Error Codes


112

Introduction to Error Codes

This section of the documentation lists the possible errors that may be returned, ordered by error number.

Note: This list comprises all error codes at the time of publication; additions and modifications may be

made without advance notice.

Here's an example of how an error will be returned to you:


<exacttarget>

<system>

<subscriber>

<error>87</error>

<error_description>An application security

violation has occurred. You are not authorized to

view the requested data. The event has been logged.

If you feel you have received this message in

error, or would like more information, please

contact us.</error_description>

</subscriber>

</system>

</exacttarget>

See Error Code Numbers and Descriptions.




API Error Codes

113

Error Code Numbers and Descriptions �� 0 through 9 �� 10 through 19 �� 20 through 29 �� 30 through 39 �� 40 through 49 �� 50 through 59 �� 60

through 69 �� 70 through 79 �� 80 through 89 �� 90 through 99 �� 100 through 109 �� 110 and higher

The following sections list all possible error codes and the primary description associated with each, along

with information on how to resolve the error. You can download the error codes and descriptions in CSV

format from the downloads area of the ExactTarget Developer Community web site:

http://developer.exacttarget.com/cs/pdf_download.aspx

The CSV contains six columns:

column

1:

error code number

column

2:

primary description associated with error

code

column

3:

second possible description that can be

associated with the error code

column

4:

third possible description that can be


column

5:

fourth possible description that can be


column

6:

fifth possible description that can be


If you require additional assistance with an error you're receiving, please contact ExactTarget Support. You

may also find the information you need at the ExactTarget Developer Community web site.

0 through 9

Code Description Troubleshooting Information

0 System is currently unavailable. Please try again later. Remember that ExactTarget

has regularly scheduled system maintenance every

Friday night at 10:00PM until Saturday morning at

4:00AM, during which time the API will be

unavailable.

1 Subscriber not found with ListID = xxx

Email Address = xxx.

The email address you specified was not found in

this list. (This error can be helpful in determining

whether the subscriber is an existing subsciber who

needs to be updated or a new subscriber to be


114

added.)

If you think that the subscriber already exists in

your account, double-check the list ID number and

the email address spelling in your call.

2 The search_value2 does not contain a

valid email address.

Check that you've entered a value in the correct

node and that the spelling and construction of the

email address in your call are correct.

3 The search_value must be numeric. Your search_value contains nonnumeric characters.

Check that the ID you're using in your call is correct

and that you haven't entered any spaces in the value

provided for this node.

4 Subscriber not found with SubId = xxx. Double-check the subscriber ID you're using in your

call. Use the Subscriber Retrieve command to

obtain the correct subscriber ID if necessary.

5 The search_value must be numeric. Same as error 3.

6 The search_type must be listid or

subid.

See the documentation of the call you're making for

the proper syntax.

7 The search_value2 must be an email

when listid is selected.


the proper syntax.

8 The list specified does not exist. Please

select a different list.

Double-check the list ID you're using in your call.

Use the List Retrieve command to obtain the correct

list ID if necessary.

9 Information must be entered in the xxx

field.

You left a required tag's value blank in your call.

10 through 19


10 The information entered in the xxx field

is not correct.

Double-check the value you entered for the tag

specified in the error message.

11 The information entered in the xxx field

is not unique.

The value you entered for the tag specified in the

error message already exists in your database and

must be a unique value.

12 An error occurred while saving the

subscriber information. Only a portion

has been saved.

Log in to the ExactTarget application or use the

Subscriber Retrieve command to view the

subscriber record as it currently stands. Then retry

the call (maximum three reattempts) you were

attempting to make, as appropriate.

API Error Codes

115

13 An error occurred while attempting to

save your subscriber data.

Log in to the ExactTarget application or use the

Subscriber Retrieve command to view the

subscriber record as it currently stands. Then retry

the call (maximum three reattempts) you were

attempting to make, as appropriate.

14 The subscriber already exists in the list. A subscriber with the email address you've specified

in your call already exists in your database. If you

are attempting to modify an existing subscriber, use

the Subscriber Edit (Update) command.

15 The subscriber you are attempting to

modify does not exist anymore.

Double-check that you've specified the correct email

address in your call.

16 An internal error has occurred. This error can be triggered by several possible

causes. Check your code and retry your call

(maximum three reattempts). If the error persists,

contact ExactTarget Support.


insert is on your unsubscribe list.

The email address specified for the new subscriber

is on your account's unsubscribe list.

If you want to take the subscriber off your account's

unsubscribe list, use the Subscriber Edit (Update)

command to modify the subscriber's status and

reactivate the subscriber.


insert is on the global unsubscribe list.

The global unsubscribe list is maintained by

ExactTarget. Subscribers on the global unsubscribe

list cannot be added to your subscriber lists. Please

contact ExactTarget Support if you need further

information.


save your subscriber data.

Same as error 13.

20 through 29


20 The search_value2 must be an email

address when listid is selected.

Same as error 7.

21 The profile was not found for the

logged in member.

Check the attributes you have defined for your

account and verify that those in your API call

match.

22 The action must be add, edit or delete. See the documentation of the call you're making for

the proper syntax.

23 An error occurred while attempting to Double-check your code for any erroneous values


116

retrieve the email. and retry the call (maximum three reattempts).

24 The search_value2 must be a

subscriber id to send to.


the proper syntax.

25 The search_type must be emailid for

jobs.


the proper syntax.

26 An invalid send date was provided. Double-check the value you provided as the send

date.

27 An invalid send time was provided. Double-check the value you provided as the send

time.

28 An error occurred while creating the

job. The email will not be sent.

Double-check your code for any erroneous values

and retry the call (maximum three reattempts).

29 The job was not sent because no lists

were provided.


the proper syntax and required fields.

30 through 39


30 The search_type must be emailid for

jobs.

Same as error 25.

31 The action must be send or

send_single.


the proper syntax.


create a list.



33 A list name can only be 50 characters

long.

Shorten the name that you've specified for the list


34 The action add must have a list_name

tag.


the proper syntax.

35 The search_type must be listid for list. See the documentation of the call you're making for

the proper syntax.

36 The list requested does not exist. Double-check the list ID you're using in your call.

Use the List Retrieve command to obtain the correct

list ID if necessary.

37 Invalid system name = xxx. See the documentation of the call you're making for

the proper syntax.

38 Invalid Tag = xxx. See the documentation of the call you're making for

API Error Codes

117

the proper syntax.

39 XML Parse Error = xxx. Proofread your code for basic XML errors.

40 through 49


40 Unauthorized user login. Double-check the username and password specified

in your call and ensure that they match an

authorized user record in your ExactTarget

application.

41 Invalid parameters. Username and

password must be provided.

The username and password are required. See How

to Construct Your Calling Application.

42 An invalid format type was given for

the parameter ""qf"".

Check that the construction of your post is correct.

See How to Construct Your Calling Application.

43 The call to this site must be secure. Check that your URL begins with https. See How to

Construct Your Calling Application.

44 An internal error has occurred. This

may be due to invalid data being

processed.

Same as error 16.

45 Could not find the event. This may be

due to invalid eventid being processed.

Double-check the event ID you're using in your call.

46 The user does not have access to this

job. This may be due invalid username

& login or jobID.

First, check that the user record whose username

and password you're specifying in your call has the

necessary rights to perform this action. Next,

double-check the job ID you're using in your call.

47 Could not check security. This may be

due invalid username & login or jobID.

First, check that the user record whose username

and password you're specifying in your call has the

necessary rights to perform this action. Next,

double-check the job ID you're using in your call.

48 Invalid jobID. Double-check the job ID you're using in your call.

Use the Tracking Retrieve Job IDs command to

obtain the correct job ID if necessary.

49 Invalid Action. Use actions in the API

document.


the proper syntax.


118

50 through 59


50 Invalid subAction. Make sure your

sub_action is valid.


the proper syntax.

51 Invalid parameters. SubID not valid.

Try using a different subscriberID

Double-check the subscriber ID you're using in your

call. Use the Subscriber Retrieve command to obtain

the correct subscriber ID if necessary.

52 An invalid format type was given for

the parameter ""qf"".

Same as error 42.

53 Category tag should be empty. A value was specified in your call for a tag that must

be blank. See the documentation of the call you're

making for the proper syntax.

54 Expecting category tag. A required tag is missing from your call. See the

documentation of the call you're making for the

proper syntax.

55 Expecting email_name tag. A required tag is missing from your call. See the


proper syntax.

56 Expecting email_subject tag. A required tag is missing from your call. See the


proper syntax.

57 Expecting email_body tag. A required tag is missing from your call. See the


proper syntax.

58 Could not create the email. This error can be triggered by several possible




60 through 69


60 Invalid Sub_action. Same as error 50.

61 Invalid action. Same as error 49.

62 System tag error. Double-check the system name specified in your

call. See the documentation of the call you're

API Error Codes

119


63 email_subject tag can not be empty. See the documentation of the call you're making for


64 email_body tag can not be empty. See the documentation of the call you're making for


65 Could not find the event. This may be

due to invalid eventid being processed

Same as error 45.

66 email_name tag can not be empty. See the documentation of the call you're making for


67 HTML feature not enabled. You cannot create an email with the API unless the

advanced HTML paste feature is enabled in your

account. Please see your ExactTarget account

manager.

68 File does not exist. The filename specified in your call is not located on

the FTP site. If you dragged the file to the FTP site a

while ago, it may have been removed as part of our

regular cleanup. Check the filename spelling in your

call. If necessary, re-drag the file to the FTP site and

retry your call (maximum three reattempts).

69 An error has occurred attempting to

import your file.

This error can be triggered by several possible




70 through 79


70 The number of fields mapped does not

match the number of fields in the

import file.

Your API call must include a <field> line for every

column in your import file, even for fields that you

want to skip. See the documentation for the proper

syntax and requirements.

71 An internal error has occurred. Same as error 16.

72 Missing required Tag - XML error. A required tag is missing from your call. See the


proper syntax.

73 Missing required Tag - XML error. Same as error 72.



120

75 An error occurred during decryption. Double-check the encryption used on your file and

the encryption format specified in your call. Contact

ExactTarget Support if you need further assistance.




79 Missing required Tag XML. Same as error 72.

80 through 89


80 Search_Type error - Invalid

Search_Type.


the proper syntax.

81 error - XML error. Proofread your code for basic XML errors.

82 Invalid start date. Double-check the value you provided as the start

date.

83 Invalid end date. Double-check the value you provided as the end

date.

84 Invalid start date. Same as error 82.

85 No subscriber activity found. This

could be because no activity has

occurred or the job is older than 90

days.

If you expected subscriber activity to be returned,

double-check the subscriber ID specified in your

call.

Remember that subscriber-level tracking data is

retained in the system for 90 days only.

87 An application security violation has

occurred. You are not authorized to

view the requested data. The event has

been logged. If you feel you have

received this message in error, or

would like more information, please

contact us.

Double-check the username and password specified

in your call and ensure that they match an

authorized user record in your ExactTarget

application.

88 The job was not sent because there was

an invalid substitution string.


the proper syntax.

89 The API option is not turned on for

your account.

In order for you to integrate with the ExactTarget

API, the advanced API feature must be enabled in

your account. See your ExactTarget account

API Error Codes

121

manager if you receive this message.

90 through 99


94 The end date is before the start date. Double-check the start and end dates specified in

your call.

95 The maximum number of listIds has

been exceeded. Please limit the number

to no more than 20.

Your list import contains too many lists. Break up

your call into two separate calls so that you do not

exceed the maximum number of lists.

98 Import Job does not exist. Double-check the import ID specified in your call.

If you're certain that the import ID is correct,

contact ExactTarget Support for assistance.

99 Sorry, we are unable to complete the

request. The subscriber specified has a

status of either 'Unsubscribed', 'Held',

'Deleted' or has been placed on the

master unsubscribe list.

The action you are attempting cannot be performed

on a non-active subscriber.

100 through 109


101 Error attempting to initialize the group

refresh event.



102 The subscriber group is currently being

refreshed. Please wait for this refresh to

complete before initiating another

refresh.

The likely cause of this error is an attempt to

execute the same group refresh more than once.

103 Maximum date range exceeded. Double-check the end date specified in your call.

The end date of your date range cannot be set in the

future.

104 EmailID provided does not exist. Double-check the email ID you're using in your

call. Use the Email Retrieve All (Email IDs)

command to obtain the correct list ID if necessary.

105 Email list could not be retrieved for the

given criteria.

Double-check the search value specified in your

call. See the documentation of the call you're


106 Given startdate or enddate is null. Double-check the start and end dates specified in

your call. See the documentation of the call you're


122

making for the proper syntax and required fields.

107 Update failed. Updating the status

using SUBID is no longer supported.

The API call you are attempting to make is not valid

with the current database structure. Please see this

documentation for all currently valid calls.

108 Invalid dates or Daterange. Double-check the start and end dates specified in

your call. See the documentation of the call you're

making for the proper syntax and required fields.

109 ChannelMemberID is required. When you import subscribers into or retrieve

subscriber information from an On Your Behalf

(Dynamic One-to-One) channel member account,

you must specify the channel member ID. See the


proper syntax and required fields.

110 and Higher


110 Missing values node. A required tag is missing from your call. See the


proper syntax.

111 No attributes provided. See the documentation of the call you're making for


112 ChannelMemberID must be numeric. Double-check the channel member ID specified in

your call.

113 Error with unsubscribe. Contact ExactTarget Support or your account

manager. Please provide the full API call that

returned this error and the date/time that you made

this API call.

114 Error activating the subscriber. Contact the ExactTarget Support or your account

manager. Please provide the full API call that

returned this error and the date/time that you made

this API call.

115 Invalid data profile attribute data. A

value you supplied is not valid for an

attribute.

Double-check the definitions of your profile and/or

preference attributes in your ExactTarget account. If

the attribute is defined to accept restricted values,

the value you provide in your call must exactly

match one of the drop-down list values defined for

that attribute in the application.

116 Mandatory data profile values not

defined.

Double-check the definitions of your profile and/or

preference attributes in your ExactTarget account.

Every attribute marked as required must be included

API Error Codes

123

when you add a subscriber (unless a default value

has been specified in the attribute definition).

117 The subscriber is on the Master

Unsubscribe list.

The email address specified for the new subscriber

is on your account's unsubscribe list.

If you want to take the subscriber off your account's

unsubscribe list, use the Subscriber Edit (Update)

command to modify the subscriber's status and

reactivate the subscriber.

118 Could not update subscriber. Email

address already exists within your

account.

A subscriber with the email address you've

specified in your call already exists in your

database. If you are attempting to modify an

existing subscriber, use the Subscriber Edit

(Update) command.

119 Email Address field must not exceed

100 characters.

Double-check that the email address is correct. It

cannot be longer than 100 characters.

119 The information entered in the

ChannelMemberID field is invalid.

Double-check the channel member ID specified in

your call.

120 The from_name and from_email must

match the user's from name and from

email.

The data in your <from_name> and <from_email>

tags does not match your account's display name

and email address.

121 The from_name and from_email must

match a user's from name and from

email.

The data in your <from_name> and <from_email>

tags does not match the name and email address

defined in the User Properties for any of the users in

your account.

122 file_name tag can not be empty. The <file_name> tag must contain a filename. See

the documentation of the call you're making for the

proper syntax and required fields.

123 Invalid data profile value(s). The profile value or values passed in the call are not

of the same data type as the attributes to which they

correspond. Double-check the data type defined for

the attributes in the application and then check the

data type of the values you're passing.

124 The redirect email sends business rule

is not turned on for your account.

You have attempted to redirected all emails for this

job to a single email address; however, your

account is not configured to support this

functionality. Contact your account administrator

for information about this functionality.

125 The account you are attempting to

access is currently undergoing

maintenance and cannot be accessed at

this time.

You have attempted to access the appication via the

API; however, your account is unavailable due to

maintenance.


124

129 The list suppression business rule is not

turned on for your account.

You have executed the Job Send (Mass Email) call

and included a value for the <suppress> node;

however, List Suppression is not an activated

feature in your account.

130 Email contains a dynamic subject line

but you do not have the Dynamic

Content business rule turned on.

You have executed the Email Add HTML Paste call

and the email body contains dynamic content;

however, Dynamic Content is not an activated

feature in your account.

131 The account that you attempted to

access currently inactive. Please

contact your account representative to

address this issue.

The ExactTarget account has expired.

3074 The given search_value was passed as

an empty element.

Double-check your code. See the documentation of

the call you're making for the proper syntax and

required fields.

125

ExactTarget Resources


126

Support �� exacttarget developer community �� system requirements �� online support form �� about exacttarget

support �� weekly site maintenance

The ExactTarget team of Software Support Specialists is available to all customers at no charge. We are

committed to listening to your issues and questions and providing you with answers as quickly as possible.

ExactTarget Developer Community

As an API developer, your first resource for support is the ExactTarget Developer Community at

http://developer.exacttarget.com. This website contains tools, tips, and a discussion forum with your peers.

System Requirements

To effectively use the ExactTarget application, your computer must meet certain system requirements.

Download the PDF describing these requirements from this location:

http://memberlandingpages.com/help/SysReq/ExactTarget_System_Requirements.pdf

Online Support Form

We are pleased to provide you the ability to submit cases or inquiries online. Simply fill out the form at

http://memberlandingpages.com/SupportForm/submission.html, and your case will be logged with our

Support team.

About ExactTarget Support

• Live technical support is available between 8:00AM and 9:00 PM Eastern Monday through

Friday.

• Email your support request to [email protected].

• During standard hours, call 866-558-9823 (toll free) or 317-275-5483 (local) to speak to a

Software Support Specialist.

• If this is an after-hours emergency, please page 317-413-2128.

Weekly Site Maintenance

Maintenance is performed on the site every Friday night at 10:00PM Eastern through Saturday morning at

4:00AM.

� Maintenance time: 10:00PM Friday to 4:00AM Saturday (Eastern).

� Standard duration: 6 hours.


127

� Potential impact:

o Possible inability to log in.

o Possible inability to perform API calls.

o Slower-than-normal system performance.

o Emails scheduled for this timeframe may not be sent until the application is back online.

You can check on the status of the ExactTarget system by using the diagnostic call.


128

Training �� access and registration instructions �� exacttarget quickstart �� fundamentals & features of email

creation �� fundamentals & features of subscribers and tracking �� fundamentals & features of html

email and template creation �� deliverability best practices in email marketing

ExactTarget offers a variety of classes led by certified trainers throughout the week. As a user, you are able

to attend class when it best fits your schedule and as often as you would like. A list is provided here of all

the ExactTarget classes, including the dates that the classes are available. If you have any questions, please

contact the ExactTarget Training team at [email protected].

Access and Registration Instructions

Instructions for accessing recorded versions of these classes can be found in the

Recorded_ExactTarget_Training_Sessions PDF.

To register for a live or recorded class, go to http://exacttarget.webex.com.

Follow these steps to use the ExactTarget Training Center that appears:

1. Find the class you want, in one of two ways:

a. You can enter a keyword into the search box, such as Quickstart or Deliverability, and

all of the classes related to that keyword will appear on your screen.

b. You can also browse under the Upcoming, Daily, Weekly, or Monthly tab.

Note: By default, the time zone shown is Eastern Daylight Saving Time. By clicking on that time

zone in the upper right-hand corner, you can change the display to your preferred time zone.

2. After you have found the class you would like to register for, click on the registration link to the

right of the class.

3. You'll be prompted for a password. Type in exact1. Then click OK.

4. A registration form will appear that allows you to pick the date you would like to attend. It will

ask for your name, email address, company, and phone number.

5. After completing the form, click on Register. This will register you for the class and send a

confirmation email with the information you need to attend the class.

If you don’t receive an email, please contact our Training team at [email protected].

6. After registering, you'll see the Setup for New Users page. In order to join the training class, you

will need to download the WebEx Training Manager. Please click on the Set Up button, which

will download and set up the WebEx Training Manager.

This setup will only take a few minutes on a high-speed Internet connection. You will only need to

do this setup one time.

7. You can then complete Steps 1 through 5 again to register for other classes.


129

ExactTarget Quickstart

The one hour ExactTarget Quickstart class is designed for those individuals who would like to receive a

high level overview of the ExactTarget application. By the end of the class, participants will understand

how to: Upload Images; Create a Template; Create an Email; Create a Content Area Box; Create a List,

Send an Email; Track Results; and Use ExactTarget’s Help Features.

This class is hosted every Wednesday at 1:00 p.m. Eastern (12:00 p.m. Central; 10:00 a.m. Pacific).

Fundamentals & Features of Email Creation

This one hour class gives participants an in-depth look at the fundamentals and feature sets centered around

our email creation capabilities. By attending the class, participants will learn how to: Use the Image,

Document, and Survey Library; Create and Use Templates; Create an Email; Creating/Storing/Retrieving

Content Area Boxes; Use Forward to a Friend; Dynamic Content; Sending an Email; and Use

ExactTarget’s Help Features.

This class is hosted every Tuesday and Thursday at 11:00 a.m. Eastern (10:00 a.m. Central; 8:00 a.m.

Pacific).

Fundamentals & Features of Subscribers and Tracking

This one hour class provides an in-depth look at the fundamentals and feature sets used to manage

subscribers and tracking emails sent from the application. By attending the class, participants will learn

how to: Create Profile and Preference Attributes; Create and Manage a Mailing List; Adding Subscribers to

a List; Creating Groups; Using ExactTarget’s All Subscribers feature; Use ExactTarget’s Tracking Tools;

Creating Reports within ExactTarget; and Use ExactTarget’s Help Features.

This class is hosted every Tuesday and Thursday at 2:00 p.m. Eastern (1:00 p.m. Central; 11:00 a.m.

Pacific).

Fundamentals & Features of HTML Email and Template Creation

This 45 minute class is designed for users who would like to use their own HTML code to create Emails

and Templates. By attending this class, participants will learn how to: Create an Email with HTML; Create

a Template with HTML; Tips and Tricks for Using HTML in the ExactTarget application; and Best

Practices when using your own HTML code.

(ExactTarget recommends that participants have a basic understanding of HTML code in order to

understand the material covered in this class.)

This class is hosted on the first and third Wednesday of the month at 11:00 a.m. Eastern (10:00 a.m.

Central; 8:00 a.m. Pacific).


130

Deliverability Best Practices in Email Marketing

This session will last approximately an hour and is open to anyone in your organization. The session will

cover the following topics: How email works, how ExactTarget tracks undeliverable emails, Deliverability

Best Practices, and ExactTarget's deliverability policies.

This class is hosted on the fourth Wednesday of the month at 11:00 a.m. Eastern (10:00 a.m. Central; 8:00

a.m. Pacific)


131

Feedback on ExactTarget Documentation

If you have any comments, suggestions, or questions regarding this help file or any other documentation

you've received from ExactTarget, please send an email to [email protected].

For support requests or questions about the application itself, please email [email protected].

exacttarget api guide.117 - amazon web...

Documents