Navidar Review of salesforce.com’s Acquisition of ExactTarget
ExactTarget API Guide.117 - Amazon Web...
Transcript of 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
ExactTarget API Guide
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
ExactTarget API Guide
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.
ExactTarget API Guide
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
ExactTarget API Guide
ExactTarget API Guide
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.
ExactTarget API Guide
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.
ExactTarget API Guide
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>
ExactTarget API Guide
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.
ExactTarget API Guide
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.
ExactTarget API Guide
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.
ExactTarget API Guide
12
Here's an example of the results returned for an API call creating a subscriber list:
<?xml version="1.0" ?>
<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:
� 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:
ExactTarget API Guide
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
Important Information about Requirements and Security
Introduction to Application Code Sample
ExactTarget API Guide
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,
ExactTarget API Guide
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.
ExactTarget API Guide
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
Important Information about Requirements and Security
ExactTarget API Guide
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:
<?xml version="1.0" ?>
<exacttarget>
<system>
<diagnostics>
<Ping>Running</Ping>
</diagnostics>
</system>
</exacttarget>
If the system is currently down, Error 0 (system unavailable) will be returned.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
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>
<search_type>listid</search_type>
<search_value>1234</search_value>
<search_value2></search_value2>
<values>
<Email__Address>[email protected]</Email__Address>
<status>active</status>
<Full__Name>Test Person</Full__Name>
ExactTarget API Guide
19
<ChannelMemberID>5678</ChannelMemberID>
</values>
<update>true</update>
</system>
XML Tag Tag Description
<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.
<?xml version="1.0" ?>
<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.
ExactTarget API Guide
20
See Also: List Add
List Import (Upload Trigger)
How to Construct Your Calling Application
Conventions and Other Information
Subscriber Edit (Update)
���� method ���� results
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>
<system_name>subscriber</system_name>
<action>edit</action>
<search_type>listid</search_type>
<search_value>63718</search_value>
ExactTarget API Guide
21
<search_value2>[email protected]</search_value2>
<values>
<First__Name>User</First__Name>
<Email__Address>[email protected]</Email__Address>
<status>unsub</status>
<reason>insert your unsubscribe reason here</reason>
<ChannelMemberID>5678</ChannelMemberID>
</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>
<system_name>subscriber</system_name>
<action>edit</action>
<search_type>subid</search_type>
<search_value>79141717</search_value>
<search_value2></searchvalue2>
<values>
<First__Name>Scott2</First__Name>
<Email__Address>[email protected]</Email__Address>
<ChannelMemberID>5678</ChannelMemberID>
</values>
</system>
Parameters
XML Tag Tag Description
<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
ExactTarget API Guide
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.
<?xml version="1.0" ?>
<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.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
23
Subscriber Retrieve
���� method ���� results
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>
<system_name>subscriber</system_name>
<action>retrieve</action>
<search_type>listid</search_type>
<search_value>123456</search_value>
<search_value2>[email protected]</search_value2>
<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>
<system_name>subscriber</system_name>
<action>retrieve</action>
<search_type>listid</search_type>
<search_value></search_value>
<search_value2>[email protected]</search_value2>
<showChannelID></showChannelID>
</system>
ExactTarget API Guide
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_name>subscriber</system_name>
<action>retrieve</action>
<search_type>subid</search_type>
<search_value>123456789</search_value>
<search_value2></search_value2>
<showChannelID></showChannelID>
</system>
Parameters
XML Tag Tag Description
<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.
When searching on subscriber ID, leave this tag's value blank. (However, the
tag must still be included; do not omit this tag.)
<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):
<?xml version="1.0" ?>
<exacttarget>
<system>
<subscriber>
<subid>125704849</subid>
<listid>63718</listid>
ExactTarget API Guide
25
<list_name>Newsletter List</list_name>
<Email__Address>[email protected]</Email__Address>
<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>
<subid>125704849</subid>
<listid>63718</listid>
<list_name>NewsletterList</list_name>
<Email__Address>[email protected]</Email__Address>
<Status>Active</Status>
<Email__Type>HTML</Email__Type>
<First__Name>John</First__Name>
<Last__Name>Doe</Last__Name>
<Title/>
<Region/>
</subscriber>
<subscriber>
<subid>125504849</subid>
<listid>63719</listid>
<list_name>TechnologyUpdate</list_name>
<Email__Address>[email protected]</Email__Address>
<Status>Active</Status>
<Email__Type>HTML</Email__Type>
<First__Name>John</First__Name>
<Last__Name>Doe</Last__Name>
<Title/>
<Region/>
</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.
ExactTarget API Guide
26
See Also: How to Construct Your Calling Application
Conventions and Other Information
Requesting Job Notifications
Subscriber Delete
���� method ���� results
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>
<system_name>subscriber</system_name>
<action>delete</action>
<search_type>listid</search_type>
<search_value>112233445566</search_value>
<search_value2>[email protected]</search_value2>
</system>
Delete Subscriber
To delete a subscriber, use the following syntax:
ExactTarget API Guide
27
<system>
<system_name>subscriber</system_name>
<action>delete</action>
<search_type>subid</search_type>
<search_value>112233445566</search_value>
<search_value2></search_value2>
</system>
Parameters
XML Tag Tag Description
<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.
When searching on subscriber ID, leave this tag's value blank. (However, the
tag must still be included; do not omit this tag.)
Results
The successful completion of this script will return a confirmation message.
<?xml version="1.0" ?>
<exacttarget>
<system>
<subscriber>
<subscriber_info> Subscriber Deleted Successfully
</subscriber_info>
</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.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
28
Subscriber Master Unsub (Master Unsubscribe List)
���� method ���� results
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>
<system_name>subscriber</system_name>
<action>masterunsub</action>
<search_type>emailaddress</search_type>
<search_value>
<emailaddress>[email protected]</emailaddress>
<emailaddress>[email protected]</emailaddress>
<emailaddress>[email protected]</emailaddress>
</search_value>
</system>
XML Tag Tag Description
<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:
ExactTarget API Guide
29
<?xml version="1.0" ?>
<exacttarget>
<system>
<subscriber>
<subscriberunsub>
<emailaddress>[email protected]</emailadd
ress>
<status>masterunsub</status>
</subscriberunsub>
<subscriberunsub>
<emailaddress>[email protected]</emailadd
ress>
<status>masterunsub</status>
</subscriberunsub>
<subscriberunsub>
<emailaddress>[email protected]</emailadd
ress>
<status>masterunsub</status>
</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>
<emailaddress>[email protected]</emailaddress>
<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.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
30
Master Unsub Retrieve
���� method ���� results
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>
<action>retrieve</action>
<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>
<system_name>tracking</system_name>
<action>retrieve</action>
<sub_action>masterunsub</sub_action>
<search_type/>
<search_value/>
<daterange/>
</system>
XML Tag Tag Description
<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.
ExactTarget API Guide
31
Results
The successful completion of this script will return output similar to the following:
<?xml version="1.0" ?>
<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>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
FTAF (Forward to a Friend) Retrieve
���� method ���� results
ExactTarget API Guide
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>
<system_name>tracking</system_name>
<action>retrieve</action>
<sub_action>ftaf</sub_action>
<search_type>jobID</search_type>
<search_value>35952</search_value>
<search_value2/>
</system>
XML Tag Tag Description
<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
The successful completion of this script will return output similar to the following:
<?xml version="1.0" ?>
<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>
ExactTarget API Guide
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>
<subscriberID>11708497</subscriberID>
<listID>12999</listID>
<firstname />
<lastname />
<email>[email protected]</email>
<type>HTML</type>
<Favorite__Color>Blue</Favorite__Color>
<FavoriteMusic>Jazz</FavoriteMusic>
</subscriber>
<subscriber>
<subscriberID>11810694</subscriberID>
<listID>12999</listID>
<firstname />
<lastname />
<email>[email protected]</email>
<type>HTML</type>
<Favorite__Color>Green</Favorite__Color>
<FavoriteMusic>Country</FavoriteMusic>
</subscriber>
<subscriber>
<subscriberID>12245237</subscriberID>
<listID>12999</listID>
<firstname />
<lastname />
<email>[email protected]</email>
<type>HTML</type>
<Favorite__Color>Orange</Favorite__Color>
<FavoriteMusic>Folk</FavoriteMusic>
</subscriber>
</subscribers>
</tracking>
</system>
</exacttarget>
ExactTarget API Guide
34
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
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
���� method ���� results
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>
XML Tag Tag Description
<search_type> and
<search_value>
Leave these tags' values blank. (Do not omit the tags.)
Results
The successful completion of this script will return output similar to the following:
<?xml version="1.0" ?>
<exacttarget>
<system>
ExactTarget API Guide
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>
<description>System default for subscribers
email address</description>
<default_value />
<data_type>text</data_type>
<required>True</required>
<min_size>0</min_size>
<max_size>2000</max_size>
<subscriber_editable>1</subscriber_editable>
<display>Email Address</display>
</attribute>
<attribute>
<name>Email Type</name>
<description>System default for subscribers
email type</description>
<default_value>HTML</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>EmailType</display>
</attribute>
</profile>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
37
List Add
���� method ���� results
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>
<system_name>list</system_name>
<action>add</action>
<search_type></search_type>
<search_value></search_value>
<list_type>public</list_type>
<list_name>Monday’s List</list_name>
</system>
XML Tag Tag Description
<search_type> and
<search_value>
Leave these tags' values blank. (Do not omit the tags.)
<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.
ExactTarget API Guide
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.
<?xml version="1.0" ?>
<exacttarget>
<system>
<list>
<list_info>List was added successfully</list_info>
<list_description>80080</list_description>
</list>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
List Edit (Rename)
���� method ���� results
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>
<system_name>list</system_name>
<action>edit</action>
<search_type>listid</search_type>
<search_value>1234</search_value>
<list_name>April06</list_name>
ExactTarget API Guide
39
</system>
XML Tag Tag Description
<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.
<?xml version="1.0" ?>
<exacttarget>
<system>
<list>
<list_info>List was modified successfully</list_info>
<list_description>80080</list_description>
</list>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
List Retrieve
���� method ���� results
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.
ExactTarget API Guide
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_name>list</system_name>
<action>retrieve</action>
<search_type>listid</search_type>
<search_value>1234</search_value>
</system>
XML Tag Tag Description
<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>
<system_name>list</system_name>
<action>retrieve</action>
<search_type>listname</search_type>
<search_value>2005</search_value>
</system>
XML Tag Tag Description
<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>
<system_name>list</system_name>
<action>retrieve</action>
<search_type>listname</search_type>
<search_value></search_value>
</system>
ExactTarget API Guide
41
XML Tag Tag Description
<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
<?xml version="1.0" ?>
<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.
ExactTarget API Guide
42
Retrieve List ID by List Name
<?xml version="1.0" ?>
<exacttarget>
<system>
<list>
<listid>12345</listid>
</list>
</system>
</exacttarget>
Retrieve All List IDs
<?xml version="1.0" ?>
<exacttarget>
<system>
<list>
<listid>12345</listid>
<listid>67890</listid>
<listid>80080</listid>
<listid>80081</listid>
<listid>80082</listid>
</list>
</system>
</exacttarget>
See Also: How to Construct Your Calling Application
Conventions and Other Information
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
ExactTarget API Guide
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>
<system_name>list</system_name>
<action>import</action>
<search_type>listid</search_type>
<search_value>112233</search_value>
<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_value>112233</search_value>
<search_value>112244</search_value>
<search_value>112255</search_value>
</search_values>
ExactTarget API Guide
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.
XML Tag Tag Description
<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.
ExactTarget API Guide
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.
<?xml version="1.0" ?>
<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>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
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
ExactTarget API Guide
46
In this example, the import file contains the following fields, in order:
� f_name
� l_name
� city
� ST
� zip
� region
� greeting
� catalog
� html
Here's the XML system statement for importing this data into the account's subscriber list with ID 112233:
<system>
<system_name>list</system_name>
<action>import</action>
<search_type>listid</search_type>
<search_value>112233</search_value>
<file_name>998770import.csv</file_name>
<email_address>[email protected]</email_address>
<file_type>csv</file_type>
<column_headings>true</column_headings>
<file_mapping>
ExactTarget API Guide
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)
How to Construct Your Calling Application
Conventions and Other Information
List Import Status Check
���� method ���� results
Purpose: Request an update on the status of an import.
Input: Import ID.
Results: A status message is returned to you.
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:
ExactTarget API Guide
48
<system>
<system_name>list</system_name>
<action>import</action>
<sub_action>importstatus</sub_action>
<search_value>119792</search_value>
</system>
XML Tag Tag Description
<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.
<?xml version="1.0" ?>
<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.
See Also: How to Construct Your Calling Application
Conventions and Other Information
List Retrieve Subscribers
���� method ���� results
ExactTarget API Guide
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>
<system_name>list</system_name>
<action>retrieve_sub</action>
<search_type>listid</search_type>
<search_value>1234</search_value>
</system>
To filter by subscriber status, add the <search_status> tag, as follows:
<system>
<system_name>list</system_name>
<action>retrieve_sub</action>
<search_type>listid</search_type>
<search_value>1234</search_value>
<search_status>Active<search_status>
</system>
XML Tag Tag Description
<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:
ExactTarget API Guide
50
<?xml version="1.0" ?>
<exacttarget>
<system>
<list>
<subscribers>
<subscriber>
<Email__Address>[email protected]</Email__Ad
dress>
<Status>Active</Status>
<Email__Type>HTML</Email__Type>
<firstName>Bob</firstName>
<lastName />
<fullname />
<Zip__Code />
<Account />
</subscriber>
<subscriber>
<Email__Address>[email protected]</Email__A
ddress>
<Status>Active</Status>
<Email__Type>HTML</Email__Type>
<firstName>Mary</firstName>
<lastName>Smith</lastName>
<fullname />
<Zip__Code />
<Account />
</subscriber>
</subscribers>
</list>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
List Delete
���� method ���� results
ExactTarget API Guide
51
Purpose: Delete a list and all subscribers who belong to the list.
Input: List ID.
Results: A confirmation message is returned to you.
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_name>list</system_name>
<action>delete</action>
<search_type>listid</search_type>
<search_value>1234</search_value>
</system>
XML Tag Tag Description
<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:
<?xml version="1.0" ?>
<exacttarget>
<system>
<list>
<list_info>List was deleted successfully</list_info>
<list_description>1234</list_description>
</list>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
52
List Retrieve Groups (All Groups)
���� method ���� results
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>
<system_name>list</system_name>
<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.
<?xml version="1.0" ?>
<exacttarget>
<system>
<list>
<groups>
<group>
<parentlistID>529007</parentlistID>
<groupID>530833</groupID>
<groupName>Marion County
Subscribers</groupName>
<description>Marion County
Subscribers</description>
</group>
<group>
<parentlistID>529007</parentlistID>
<groupID>530837</groupID>
<groupName>New Customers</groupName>
<description>Subscribers with Accounts 1
Year or Less</description>
</group>
ExactTarget API Guide
53
<group>
<parentlistID>529007</parentlistID>
<groupID>530843</groupID>
<groupName>Hamilton County
Subscribers</groupName>
<description>Hamilton County
Subscribers</description>
</group>
</groups>
</list>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
List Refresh Group
���� method ���� results
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>
ExactTarget API Guide
54
<system_name>list</system_name>
<action>refresh_group</action>
<sub_action/>
<search_value>1234</search_value>
<search_value2/>
</system>
XML Tag Tag Description
<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.
<?xml version="1.0" ?>
<exacttarget>
<system>
<list>
<groupRefresh>
<groupID>363083</groupID>
<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:
<?xml version="1.0" ?>
<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.
ExactTarget API Guide
55
See Also: How to Construct Your Calling Application
Conventions and Other Information
Group Refresh Status Check (Batch Inquire)
���� method ���� results
Purpose: Request an update on the status of a group refresh.
Input: Async ID (ID generated for the refresh request).
Results: A status message is returned to you.
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_value>119792</search_value>
<search_value2/>
</system>
XML Tag Tag Description
<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.
<?xml version="1.0" ?>
<exacttarget>
<system>
<Batch>
ExactTarget API Guide
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.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
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>
<action>retrieve</action>
<sub_action>all</sub_action>
<search_type></search_type>
<search_value></search_value>
<search_value2></search_value2>
<daterange></daterange>
</system>
To retrieve the email ID for a specific email name, use the following syntax:
<system>
<system_name>email</system_name>
<action>retrieve</action>
<sub_action>all</sub_action>
<search_type>emailname</search_type>
<search_value>Welcome to Fortune One!</search_value>
<search_value2></search_value2>
ExactTarget API Guide
58
<daterange></daterange>
</system>
To retrieve the email ID of every email created during a specific period, use the following syntax:
<system>
<system_name>email</system_name>
<action>retrieve</action>
<sub_action>all</sub_action>
<search_type>daterange</search_type>
<search_value></search_value>
<search_value2></search_value2>
<daterange>
<startdate>9/15/2005</startdate>
<enddate>10/15/2005</enddate>
</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>
<system_name>email</system_name>
<action>retrieve</action>
<sub_action>all</sub_action>
<search_type>emailnameanddaterange</search_type>
<search_value>Welcome to Fortune One!</search_value>
<search_value2></search_value2>
<daterange>
<startdate>9/15/2005</startdate>
<enddate>10/15/2005</enddate>
</daterange>
</system>
XML Tag Tag Description
<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
The successful completion of this script will return output similar to the following.
<?xml version="1.0"?>
<exacttarget>
ExactTarget API Guide
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>
<emailid>138167</emailid>
<emailname>Conversion Tracking</emailname>
<emailsubject>Conversion Tracking Advanced
Test</emailsubject>
<emailcreateddate>9/23/2003</emailcreateddate>
<categoryid>75163</categoryid>
</emaillist>
<emaillist>
<emailid>205449</emailid>
<emailname>ET 04 Demo Email</emailname>
<emailsubject>ET 04 Demo Email</emailsubject>
<emailcreateddate>3/19/2004</emailcreateddate>
<categoryid>75163</categoryid>
</emaillist>
</email>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
Email Add HTML Paste
���� method ���� results
Purpose: Create an email from HTML that you send to the ExactTarget application via an API
call.
ExactTarget API Guide
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:
ExactTarget API Guide
61
<system>
<system_name>email</system_name>
<action>add</action>
<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:
ftp://ftp.exacttarget.com
For complete details on using the ExactTarget FTP site, see the FTP Instruction Guide PDF.
Then submit your call, using the following syntax:
<system>
<system_name>email</system_name>
<action>add</action>
<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
XML Tag Tag Description
<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
ExactTarget API Guide
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.
<?xml version="1.0"?>
<exacttarget>
<system>
<email>
<emailID>44180</emailID>
</email>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: FTP Instruction Guide (PDF)
How to Construct Your Calling Application
Conventions and Other Information
Email Add Text Version
���� method ���� results
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.
Results: A confirmation message is returned to you.
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
ExactTarget API Guide
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>
<system_name>email</system_name>
<action>add</action>
<sub_action>text</sub_action>
<search_type>emailid</search_type>
<search_value>155324</search_value>
<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:
ftp://ftp.exacttarget.com
For complete details on using the ExactTarget FTP site, see the FTP Instruction Guide PDF.
Then submit your call, using the following syntax:
<system>
<system_name>email</system_name>
<action>add</action>
<sub_action>text</sub_action>
<search_type>emailid</search_type>
<search_value>155324</search_value>
<file_name>Filename</file_name>
</system>
Parameters
XML Tag Tag Description
<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.
ExactTarget API Guide
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.
<?xml version="1.0"?>
<exacttarget>
<system>
<email>
<email_info>Email updated successfully/email_info>
</email>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
Email Retrieve Body
���� method ���� results
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
ExactTarget API Guide
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>
<system_name>email</system_name>
<action>retrieve</action>
<sub_action>htmlemail</sub_action>
<search_type>emailid</search_type>
<search_value>12344556</search_value>
<search_value2></search_value2>
<search_value3></search_value3>
</system>
XML Tag Tag Description
<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
The successful completion of this script will return output similar to the following.
<?xml version="1.0"?>
<exacttarget>
<system>
<email>
<emailid>932890</emailid>
<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>
ExactTarget API Guide
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-right-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>
<td style="padding-right: 10px;
padding-left: 10px;
border-left-style: None;
border-right-style: None;
border-bottom-style: None;
background-color: #ff97ff;"
bgcolor=#FF97FF
ExactTarget API Guide
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>
<td style="padding-right: 10px;
padding-left: 10px;
border-left-style: None;
border-right-style: None;
border-bottom-style: None;
background-color: #ff97ff;"
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.
<?xml version="1.0"?>
<exacttarget>
<system>
<email>
<emailid>808022</emailid>
ExactTarget API Guide
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"
type="content"></td>
</tr>
<tr>
<td valign="top"><custom name="cell11"
type="content"></td>
</tr>
<tr>
<td valign="top"><custom name="cell12"
type="content"></td>
</tr>
<tr>
<td valign="top"><custom name="cell13"
type="content"></td>
</tr>
<tr>
<td width="100%" height="16%" colspan="2"
valign="top"><custom name="cell3"
type="content"></td>
</tr>
<tr>
<td width="100%" height="16%" colspan="2"
valign="top"><custom name="cell4"
type="content"></td>
</tr>
<tr>
<td width="100%" height="16%" colspan="2"
valign="top"><custom name="cell5"
type="content"></td>
</tr>
<tr>
ExactTarget API Guide
69
<td width="100%" height="16%" colspan="2"
valign="top"><custom name="cell6"
type="content"></td>
</tr>
<tr>
<td width="100%" height="16%" colspan="2"
valign="top"><custom name="cell7"
type="content"></td>
</tr>
<tr>
<td width="100%" height="16%" colspan="2"
valign="top"> <custom name="cell8" type="content">
</td>
</tr>
<tr>
<td width="100%" height="16%" colspan="2"
valign="top"> <custom name="cell9" type="content">
</td>
</tr>
</table></td></tr></table><custom
name="opencounter"
type="tracking"></body>]]></htmlbody>
</email>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
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)
���� method ���� results
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>
<search_type>emailid</search_type>
<search_value>112233</search_value>
<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>
ExactTarget API Guide
71
<list>12346</list>
</lists>
<suppress>
<list>12345</list>
<list>12346</list>
</suppress>
<test_send>true</test_send>
</system>
XML Tag Tag Description
<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)
ExactTarget API Guide
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.
<?xml version="1.0"?>
<exacttarget>
<system>
<job>
<job_info>Job was successfully created.</job_info>
<job_description>2030602</job_description>
</job>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
Job Send Single
���� method ���� results
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),
ExactTarget API Guide
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_type>emailid</search_type>
<search_value>112233</search_value>
<search_value2>1001992233</search_value2>
<from_name></from_name>
<from_email></from_email>
</system>
XML Tag Tag Description
<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.
<?xml version="1.0"?>
<exacttarget>
<system>
<job>
<job_info>Job was successfully created.</job_info>
<job_description>2030602</job_description>
</job>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
ExactTarget API Guide
74
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
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
���� method ���� results
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>
<system_name>tracking</system_name>
<action>jobretrieve</action>
<sub_action>jobs</sub_action>
<search_type>daterange</search_type>
<search_value>9/15/2005 10:30:00AM</search_value>
<search_value2></search_value2>
</system>
XML Tag Tag Description
<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.
ExactTarget API Guide
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
The successful completion of this script will return output similar to the following.
<?xml version="1.0"?>
<exacttarget>
<system>
<tracking>
<jobs>
<job>
<jobID>2030420</jobID>
<jobSendDate>9/29/2005 9:42:00
AM</jobSendDate>
<lists>
<listID>573888</listID>
</lists>
</job>
<job>
<jobID>2030416</jobID>
<jobSendDate>9/29/2005 9:50:00
AM</jobSendDate>
<lists>
<listID>573888</listID>
</lists>
</job>
<job>
<jobID>2030718</jobID>
<jobSendDate>9/29/2005 10:14:00
AM</jobSendDate>
<lists>
<listID>530837</listID>
</lists>
</job>
</jobs>
</tracking>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
ExactTarget API Guide
77
See Also: How to Construct Your Calling Application
Conventions and Other Information
Tracking Retrieve Summary
���� method ���� results
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>
<system_name>tracking</system_name>
<action>retrieve</action>
<sub_action>summary</sub_action>
<search_type>jobID</search_type>
<search_value>39408</search_value>
<search_value2></search_value2>
</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.
XML Tag Tag Description
<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).
<search_value2> Leave the value for this tag blank. (Do not omit the tag.)
Results
The successful completion of this script will return the tracking data for the email send. Here's an example:
ExactTarget API Guide
78
<?xml version="1.0"?>
<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>
<email_forwarders>0</email_forwarders>
<new_recipients>0</new_recipients>
<new_subscribers>0</new_subscribers>
</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>
<click_throughs>0</click_throughs>
ExactTarget API Guide
79
<Percent>0.0%</Percent>
<Net_CTR>0.0%</Net_CTR>
</link>
<link>
<URL>http://cl.exct.net/unsub_center.
aspx?s=%%ex2;
subscriberid%%&j=fe9c157675620578
75</URL>
<name>Unsubscribe</name>
<click_throughs>0</click_throughs>
<Percent>0.0%</Percent>
<Net_CTR>0.0%</Net_CTR>
</link>
</email_links>
<Conversion_Summary />
</emailSummary>
</tracking>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
Tracking Retrieve (Bulk Export)
���� method ���� results
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;
ExactTarget API Guide
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>
<system_name>tracking</system_name>
<action>retrieve</action>
<sub_action>all</sub_action>
<search_type>jobID</search_type>
<search_value>39408</search_value>
<search_value2></search_value2>
<daterange>
<startdate>1/1/2005</startdate>
<enddate>1/31/2005</enddate>
</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>
<system_name>tracking</system_name>
<action>retrieve</action>
<sub_action>all_attributes</sub_action>
<search_type>jobID</search_type>
<search_value>39408</search_value>
<search_value2></search_value2>
</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.
XML Tag Tag Description
<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).
<search_value2> Leave the value for this tag blank. (Do not omit the tag.)
<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.
ExactTarget API Guide
81
Results
The successful completion of this script will return the tracking data for the email send.
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
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:
<?xml version="1.0" ?>
<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>
<email_forwarders>4</email_forwarders>
<new_recipients>4</new_recipients>
<new_subscribers>0</new_subscribers>
</FTAF_summary>
<email_links>
<link>
<URL>http://brochuresite.exacttarget.
com/policies/ anti_spam.asp</URL>
<name></name>
<click_throughs>0</click_throughs>
<Percent>0.0%</Percent>
ExactTarget API Guide
82
<Net_CTR>0.0%</Net_CTR>
</link>
</email_links>
<Conversion_Summary />
</emailSummary>
<subscribers>
<subscriber>
<subscriberID>1887619908</subscriberID>
<listID>530843</listID>
<firstname>D.</firstname>
<lastname>Smith</lastname>
<email>[email protected]</email>
<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>
<subscriberID>1887619921</subscriberID>
<listID>530833</listID>
<firstname>
</firstname>
<lastname>
</lastname>
<email>[email protected]</email>
<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>
ExactTarget API Guide
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>
<subscriberID>1887619908</subscriberID>
<listID>530843</listID>
<firstname>D.</firstname>
<lastname>Smith</lastname>
<email>[email protected]</email>
<type>HTML</type>
<status>Active</status>
<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>
<clickUrl><![CDATA[http://cl.exct.net/prof
ile_center.aspx?
s=%%ex2;subscriberid%%]]></clickUrl>
</clicks>
<unsubscribe />
<surveyResponses />
<conversions />
</subscriber>
<subscriber>
<subscriberID>1887619921</subscriberID>
<listID>530833</listID>
<firstname>Leona</firstname>
<lastname>Damon</lastname>
<email>[email protected]</email>
<type>TEXT</type>
<status>Returned</status>
ExactTarget API Guide
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.
ExactTarget API Guide
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.
See Also: How to Construct Your Calling Application
Conventions and Other Information
Tracking Retrieve Single Subscriber
Tracking Retrieve Summary
Tracking Bulk Async
Tracking Retrieve Single Subscriber
���� method ���� results
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:
ExactTarget API Guide
86
<system>
<system_name>tracking</system_name>
<action>retrieve</action>
<sub_action>single</sub_action>
<search_type>jobID</search_type>
<search_value>39408</search_value>
<search_value2>300400108</search_value2>
</system>
XML Tag Tag Description
<search_value> Job ID of the email send for which you want to retrieve tracking data.
<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.
<?xml version="1.0" ?>
<exacttarget>
<system>
<tracking>
<subscribers>
<subscriber>
<subscriberID>1887619908</subscriberID>
<listID>530843</listID>
<firstname>D.</firstname>
<lastname>Smith</lastname>
<email>[email protected]</email>
<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>
<subscribers>
</tracking>
</system>
ExactTarget API Guide
87
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
Tracking Retrieve Unsubscribes
���� method ���� results
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>
<action>retrieve</action>
<sub_action>unsubscribe</sub_action>
<search_type>daterange</search_type>
<search_value>9/1/2005</search_value>
<search_value2>12/31/2005</search_value2>
</system>
XML Tag Tag Description
<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.
ExactTarget API Guide
88
Results
The successful completion of this script will return the unsubscribe date and attribute data for all
unsubscribes during the specified period.
<?xml version="1.0" ?>
<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>
<Email__Type>HTML</Email__Type>
<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>
<Email__Type>HTML</Email__Type>
<Interest>Camping</Interest>
</subscriber>
<subscribers>
</tracking>
</system>
</exacttarget>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: How to Construct Your Calling Application
Conventions and Other Information
ExactTarget API Guide
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)
���� method ���� results
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
For complete details on using the ExactTarget FTP site, see the FTP Instruction Guide PDF.
Upload your image file or files by dragging and dropping them at the FTP site:
ftp://ftp.exacttarget.com
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>
ExactTarget API Guide
90
</source>
</system>
XML Tag Tag Description
<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.
<?xml version="1.0"?>
<exacttarget>
<system>
<filemanagement>
<filemanagement-file>
<filemanagement-
filename>3611148524319.jpg</filemanagement-
filename>
<filemanagement-info>Moved</filemanagement-
info>
</filemanagement-file>
</filemanagement>
<filemanagement>
<filemanagement-file>
<filemanagement-
filename>35623314819.jpg</filemanagement-
filename>
<filemanagement-info>Moved</filemanagement-
info>
</filemanagement-file>
<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-file>
<filemanagement-
filename>20502Logo1.jpg</filemanagement-
filename>
ExactTarget API Guide
91
<filemanagement-info>file did not
exist</filemanagement-info>
</filemanagement-file>
If an error occurs, the error code will be returned in XML format for the appropriate error trapping routine
to be implemented.
See Also: FTP Instruction Guide (PDF)
How to Construct Your Calling Application
Conventions and Other Information
93
API Application Code Samples
ExactTarget API Guide
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.
API Application Code Samples
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
ExactTarget API Guide
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
API Application Code Samples
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.
ExactTarget API Guide
98
ASP Example: Add List
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.
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
API Application Code Samples
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)
ExactTarget API Guide
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>
API Application Code Samples
101
ASP Example: Retrieve Tracking Data
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.
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
ExactTarget API Guide
102
strXML = "<?xml version=" &chr(34) &"1.0"& chr(34)&
"?><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>"
' 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("bulkexport.xml"))
' Get the first subscriber in the XML Doc and get the number
' Node names are case sensitive
set objNodeList = objXML.GetElementsByTagName("subscriber")
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)
set objChildren = objChildnode.childnodes
API Application Code Samples
103
' 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."
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>
ExactTarget API Guide
104
ASP Example: Add HTML Paste Email
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.
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
API Application Code Samples
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%"
strXML = "<?xml version=" &chr(34) &"1.0"& chr(34)&
"?><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
cellpadding="& chr(34)_
& "3"& chr(34) & " cellspacing="& chr(34) & "0"& chr(34) & "
border="& chr(34)_
ExactTarget API Guide
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
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) &
"><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/'>"_
API Application Code Samples
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)_
& " 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)_
& " align="& chr(34) & "center"& chr(34) & "><img
src='https://www.exacttarget.com/members/images/27812707055475.jpg'>
"_
ExactTarget API Guide
108
&"</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) &
"></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)_
& " 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) & "><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>"_
&"</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) & "></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>"
' 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"
API Application Code Samples
109
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("emailadd.xml"))
' Get the first subscriber in the XML Doc and get the list info
' Node names are case sensitive
set objNodeList = objXML.GetElementsByTagName("email")
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(intCnt2)
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 needed to perform a comparison you could either 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."
Response.write "Status " & objSXH.status & "<br>"
ExactTarget API Guide
110
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>
111
API Error Codes
ExactTarget API Guide
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:
<?xml version="1.0" ?>
<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.
See Also: How to Construct Your Calling Application
Important Information about Requirements and Security
Conventions and Other Information
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
associated with the error code
column
5:
fourth possible description that can be
associated with the error code
column
6:
fifth possible description that can be
associated with the error code
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
ExactTarget API Guide
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.
See the documentation of the call you're making for
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
Code Description Troubleshooting Information
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.
17 The subscriber you are attempting to
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.
18 The subscriber you are attempting to
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.
19 An error occurred while attempting to
save your subscriber data.
Same as error 13.
20 through 29
Code Description Troubleshooting Information
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
ExactTarget API Guide
116
retrieve the email. and retry the call (maximum three reattempts).
24 The search_value2 must be a
subscriber id to send to.
See the documentation of the call you're making for
the proper syntax.
25 The search_type must be emailid for
jobs.
See the documentation of the call you're making for
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.
See the documentation of the call you're making for
the proper syntax and required fields.
30 through 39
Code Description Troubleshooting Information
30 The search_type must be emailid for
jobs.
Same as error 25.
31 The action must be send or
send_single.
See the documentation of the call you're making for
the proper syntax.
32 An error occurred while attempting to
create a list.
Double-check your code for any erroneous values
and retry the call (maximum three reattempts).
33 A list name can only be 50 characters
long.
Shorten the name that you've specified for the list
and retry the call (maximum three reattempts).
34 The action add must have a list_name
tag.
See the documentation of the call you're making for
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
Code Description Troubleshooting Information
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.
See the documentation of the call you're making for
the proper syntax.
ExactTarget API Guide
118
50 through 59
Code Description Troubleshooting Information
50 Invalid subAction. Make sure your
sub_action is valid.
See the documentation of the call you're making for
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
documentation of the call you're making for the
proper syntax.
56 Expecting email_subject tag. A required tag is missing from your call. See the
documentation of the call you're making for the
proper syntax.
57 Expecting email_body tag. A required tag is missing from your call. See the
documentation of the call you're making for the
proper syntax.
58 Could not create the email. 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.
60 through 69
Code Description Troubleshooting Information
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
making for the proper syntax.
63 email_subject tag can not be empty. See the documentation of the call you're making for
the proper syntax and required fields.
64 email_body tag can not be empty. See the documentation of the call you're making for
the proper syntax and required fields.
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
the proper syntax and required fields.
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
causes. Check your code and retry your call
(maximum three reattempts). If the error persists,
contact ExactTarget Support.
70 through 79
Code Description Troubleshooting Information
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
documentation of the call you're making for the
proper syntax.
73 Missing required Tag - XML error. Same as error 72.
74 An internal error has occurred. Same as error 16.
ExactTarget API Guide
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.
76 Missing required Tag - XML error. Same as error 72.
77 An internal error has occurred. Same as error 16.
78 Missing required Tag - XML error. Same as error 72.
79 Missing required Tag XML. Same as error 72.
80 through 89
Code Description Troubleshooting Information
80 Search_Type error - Invalid
Search_Type.
See the documentation of the call you're making for
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.
See the documentation of the call you're making for
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
Code Description Troubleshooting Information
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
Code Description Troubleshooting Information
101 Error attempting to initialize the group
refresh event.
Double-check your code for any erroneous values
and retry the call (maximum three reattempts).
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
making for the proper syntax.
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
ExactTarget API Guide
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
documentation of the call you're making for the
proper syntax and required fields.
110 and Higher
Code Description Troubleshooting Information
110 Missing values node. A required tag is missing from your call. See the
documentation of the call you're making for the
proper syntax.
111 No attributes provided. See the documentation of the call you're making for
the proper syntax and required fields.
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.
ExactTarget API Guide
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
ExactTarget API Guide
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.
ExactTarget Resources
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.
ExactTarget API Guide
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.
ExactTarget Resources
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).
ExactTarget API Guide
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)
ExactTarget Resources
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].