iPost XMLRPC API Documentation: XML API Use and Maintenance

The current iPost XMLRPC apiVersion Number is: 9.

This document is for informational purposes only. Technical specifications for APIs are found in their respective documentation. Terms and any required pricing will be specified in a signed iPost Services Agreement and Software License and/or iPost Statement of Work.


This document is intended to familiarize IT managers and data integrators with the scope of technical effort required to establish and maintain data exchanges through iPost's XMLRPC Application Programming Interfaces (APIs). It summarizes procedures for database setup, mailing list transfer, programmatic "triggering" of mailing deliveries, and error detection and recovery. The discussion is focused on automated processing of recipient data, and assumes that other mailing content is managed through the web-based iPost Mailing Manager user interface. Specific details about each API are covered in other documentation.

iPost provides the following APIs for access to its services:

These APIs are designed to facilitate on-demand transmission of data among iPost and iPost's clients or their third-party integrators (for example, reservation management systems and loyalty program providers). The API for ticket management is intended for use by service resellers who are creating their own user interfaces. Periodic data conduits for pre-scheduled automatic data transfer between iPost and its clients' systems, using a variety of other formats and mechanisms, are also available. See iPost Data Conduits.

Return to Top
Setup Performed by iPost

iPost Client Services is responsible for setup and modifications of iPost's systems to support client API usage. Some of this setup is the same for every client, even those who do not use an iPost API.

  1. Database setup

    iPost sets up an initial data layout in its systems to match the columns of data that you plan to transmit via the List Upload API. Examples include first name, last name, street address, preferred customer program membership, etc. The only required data is the contact's email address, which is treated as a unique key. If you have assigned another unique identifier to each contact, iPost can arrange to maintain that column as a key.

  2. XMLRPC access

    Access to the APIs is secured by:

    • use of HTTP/S encrypted communications with the API server
    • password-protected sessions that automatically expire after a limited time

    iPost creates the necessary iPost Mailing Manager (iMM) accounts for the Session Initiation API, using an email address and password determined by agreement with the client. Alternatively, a client user with administrative access to the iPost Mailing Manager may create these API accounts.

    The same, or additional, accounts may be used for access to the web-based iMM user interface.

    iPost then assigns the HTTP/S URL that is to be used by the client to post XML-RPC method calls. This URL normally uses the host conduit.ipost.com and contains a path ending in xmlrpc, but host or path may vary at iPost's discretion. An example of such a URL is:

  3. Message personalization setup

    The iMM supports message content personalization in the Subject header and anywhere in the HTML, text, or AOL message body parts. Message personalization is performed with macros written in the iPost Template Language (iTL). Usage documentation and examples of these macros is provided in the iPost Template Language technical guide.

    iPost creates any additional macros required by the client for access to the recipient data columns or for application of business rules requested by the client.

  4. Preferences form setup

    iPost typically provides a subscription preferences web form, hosted on iPost servers but private-labeled to display the client's branding, to satisfy the legal and contractual requirements that every message iPost delivers must contain a working Internet-based opt-out mechanism. If the client chooses to host this form instead, or to provide an alternate opt-out mechanism, iPost works with the client to assure that opt-out requests and suppression lists are exchanged in a timely fashion.

    The List Upload API provides a mechanism for transmitting suppression ("opt out") lists to iPost.

Return to Top
Setup Performed by client

The term client as used in this section refers to the IT department of a business that makes use of iPost's email services, or to a third-party partner of such a business, acting as a data integrator.

  1. List upload and data transfer
    1. Data definitions

      The client is responsible for determining the data layout (also known as "schema") for each column of data that is to be transmitted via the List Upload API, for providing that layout to iPost in advance of its first data transfer, and for describing to iPost any associated business rules.

      In most cases this occurs once when the client relationship with iPost is first established. Occasionally, a client needs to update the schema or business rules. A user interface is provided for this purpose in the iPost Mailing Manager

    2. Data marshaling for API calls

      API calls are by HTTP/S POST of XML structured text in the format described by http://www.xmlrpc.com/spec. The call signatures for each iPost API are defined in its respective specification. The Triggered Mailing API requires that all data, including the list of recipients, be formatted in XML. The List Upload API provides more flexibility, supporting a variety of file formats encoded as base64 text within the XML procedure call structure. This includes tab- and comma- separated columnar data files that can be exported directly from many databases and spreadsheet programs.

      The client is responsible for any programming necessary to:

      • create the formatted file of recipient data, e.g., by export from the client's database
      • package the file in the appropriate XML structure for the API procedure call
      • perform an HTTP/S POST of the XML to the iPost RPC server and receive a response
      • examine the response for possible faults in processing
  2. Session management

    Each series of API calls must begin by establishing a session by posting the account email address and password to the Session Initiation API. A valid session key is required for all other API calls. A session key remains valid until the session is explicitly terminated via the Session Termination API, or after four hours of inactivity.

    The client is responsible for programming necessary to establish sessions, and to propagate the session key to other API calls. All programs using the APIs should be prepared to handle faults returned when a session has expired.

  3. Mailing ticket setup

    For each mailing ticket, the client is responsible for:

    • providing a valid reply address and descriptive subject for the messages
    • identifying the list of recipients (or indicating that the mailing is "triggered")
    • transmitting to iPost one document for each desired delivery format (HTML, text, and optionally AOL)
    • setting the delivery schedule for the messages (when delivery begins and how rapidly it proceeds)

    This setup is performed through the iMM user interface for each new mailing. Ongoing client IT effort is required only to marshal and transmit any new recipient list data, as described above.

  4. Triggered mailing setup

    iPost mailing deliveries may broadly be viewed in two categories:

    • A simple mailing uses the mailing ticket only once, to deliver messages to the recipients at a single preset date and time
    • A "triggered" mailing uses the same ticket repeatedly, to deliver on a recurring schedule or upon occurrence of some external event

    In either case, a new ticket is created whenever there is any significant change to the message content.

    Mailings are typically approved and launched by the iPost Client Services staff, following standard procedures described in the iPost Services Agreement. This applies only once for each triggered mailing, after which subsequent deliveries do not require approval. However, iPost places more strict limits on the number of recipients in a single triggering event. Triggered mailings are also reported cumulatively – that is, each new delivery adds to the statistics gathered for previous deliveries, until a new ticket is created.

    Additional procedures apply in the case of tickets that are available via the Triggered Mailing API. The client must determine a map category name and type keyword to identify the collection of tickets (campaign folder in the iMM UI) that is used for each call to the Triggered Mailing API. The category and type may be assigned to a collection when it is created in the iMM, or the Ticket and Document API may be used to assign these names and keywords. Usually the map name designates a broad category (e.g., "transaction receipt") and the keyword a specific type (e.g., "confirm", "change", "cancel").

Return to Top
  1. Mailing schedules

    In the iPost system, when two simple mailings are going on at the same time, and the recipient lists overlap, the most recently transmitted per-recipient data is used for both mailings. For triggered mailings, the per-recipient content is stored in a transient table, so overlapping deliveries are independent.

    The client is responsible for scheduling mailings and API data transfers so that the correct recipient data is available at the time of delivery.

  2. Error detection and recovery
    1. List upload

      Upon receipt of a List Upload API call, the iPost RPC server validates that the XML data is well-formed, and that the entire file contains the correct number of data columns (for files in columnar format) with the correct column names (for any format). An error is returned if any of these validations fails. For individual recipient records, the email address syntax is validated and records with invalid addresses are skipped. iPost does not validate data in other columns unless the client has provided business rules to iPost Client Services for doing so.

      The API response describes the number of valid and invalid records, and an additional call can be made to retrieve the skipped records after the import is complete.

      Email notification of the RPC call result is also supported, as a contingency in the event that the HTTP connection is lost before the response has been received.

      As a final failsafe, the iMM website can be used to check that the expected number of records was processed.

    2. Triggered mailings

      Upon receipt of a Triggered Mailing API call, the iPost RPC server validates only that the XML data is well-formed and that limitations on the number of recipients have not been exceeded. A successful response indicates how many recipients were enqueued. Individual recipient data validation such as email address syntax check is performed asynchronously as a batch process, for efficiency and to assure a rapid response to the API call.

      iPost monitors triggered mailing deliveries and can arrange to notify the client by email of delivery failures.

      Each mailing ticket has an end date after which further deliveries of that mailing are prohibited. The duration of a mailing may be adjusted through the iMM website or via the ticketSchedule API procedure.

Return to Top
© 2010 iPost. All rights reserved.