Recent pages

Edit
page

New
page

Print
page
Page last modified 17:25, 6 Jan 2012 by Admin
0
Redirect
Page Notifications Off
Documentation Wiki > Developer Documentation > XML API > ExactTarget XML API Technical Reference > Constructing Your Calling Application

Constructing Your Calling Application

From $1

    Doc-Wiki-BannerHK.png

    (Click the banner to go to the related Docs.Code.ExactTarget.com page.)

    This documentation contains conceptual and procedural information about constructing your XML API calling application. It provides XML examples that can be mapped to HTTPS calls.

    What Is a Calling Application

    A calling application allows you to interact with the XML API by sending call to the ExactTarget XML API endpoint. 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.

    Why Construct a Calling Application

    You must use a calling application to make your API calls to the ExactTarget XML API.

    How to Construct your Calling Application

    Follow the instructions below to construct your calling application.

    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 (contained within a set of <system> tags):
      • Subscriber
      • List
      • Jobs
      • Tracking
      • Email

    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.
    <password> The password associated with the username.

    HTTP Construction

    XML can be passed in a URL query string, using GET to build the query string or manually constructing the query string. Another option is to post the data using HTTPPost.

    GET

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

    https://api.dc1.exacttarget.com/integrate.aspx?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://api.dc1.exacttarget.com/integrate.aspx?qf=xml&xml=<?xml version="1.0"?><exacttarget><authorization><username>username</username> <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> test.person@company.com</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.

    When using a query string 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.

    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 Query String

    You can allow users to navigate to a specific page in the ExactTarget application directly from your website without requiring them to log in to the ExactTarget application. To do so, you place a link on your site that passes the appropriate parameters to ExactTarget.

    The parameters are as follows:

    Parameter Description
    username The username associated with a user record in your ExactTarget security that has the access rights necessary to perform the action.
    password The password associated with the username.
    entityType

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

    Possible entityType values:

    • email
    • subscribers
    • tracking
    • libraries
    • admin
    entityID (optional) The system ID associated with the item that you want to open (email ID, list ID, job ID).
    If entityID is not provided, the main folder for the entityType (My Emails, for example) will be displayed.

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

    https://members.exacttarget.com/Login.aspx?username=username&password=password&entityType=subscribers&entityID=12345

    After authenticating the username and password, ExactTarget takes the user directly to the subs_list.asp page and displays a list of subscribers on the list with list ID 12345.

    NOTE: Be sure to URL-encode your characters.

    This page was last updated by Ryan Williams on Fri, 06 Jan 2012 21:25:54 GMT.

    If you require assistance with the ExactTarget application, please contact Global Support. If you wish to send Ryan direct feedback, fill out the form below:

     

    Was This Page Helpful?
    Suggestions or Comments:
    Name (optional):
    Email Address (optional):
    Enter 11045 backwards:
       
    Tags: (Edit tags)
    • No tags
    Attach file or image
    Files (0)
     
    Comments (0)
    You must login to post a comment.

     
    Powered by MindTouch 2010
    Admin