Why Migrate to API Version 4?

Thinking of migrating to API version 4 but still on the fence? Version 4 of the API offers many enhancements and upgrades to version 3 of the API. Check out the list below to see some of the many benefits API version 4 has to offer!

  • Parity with the most current features added to the web-based application. As new features get added to the web-based application, support for these features will also be included in version 4 of the API. NOTE: We will not be adding any new functionality to version 3 of the API, but will continue to support it in it's current state.
  • In version 4, we have broken out the write functions into two distinct function calls; add and update. This allows for a clear distinction between the addition and the update of objects. Where necessary, we have added convenience functions that perform dual adds/updates in a single call.
  • We've added common object attributes across add, update and delete function calls for given objects. For function calls where data is being read, the parameters for each function are unique to the object being read, however, the filter operators are common across all read functions.
  • Enhanced filter operators that includes support for date value specific operators (SameDay, Before, SameYear, etc.) and partial match operators (StartsWith, EndsWith, DoesNotStartWith, etc.)
  • Version 4 Allows for agency level account administration (More robust account object parameters).
  • API token level management with per token permissions. This means you can create tokens and grant API version 4 access via the API. You can also set different levels of access for different tokens (read, write, and send).
  • A conversion object that allows you to create, store, and retrieve conversion data using the API.
  • A Delivery Groups object that allows you to manage (add, read, update, and delete) delivery groups.
  • A combined header/footer object that allows you to manage header/footers via the API. There is no way to manage headers in version 3.
  • A Login object that allows for management of application users (add, read, update, and delete).
  • A Message Rules object that allows for management (add, read, update, and delete) of automated message rules. In version 3, you could associate a delivery with an automated message rule, but you couldn't actually create and manage the automated message rule.
  • When a contact object is returned using readContacts, the contact object includes additional performance data about the contact. You can find out the following:
    • The number of deliveries sent to the contact.
    • The number of bounces that have resulted from sending to the contact.
    • The number of opens recorded for the contact.
    • The number of clicks recorded for the contact.
    • The number of conversions recorded for the contact.
    • The sum/total amount of conversions recorded for the contact.
  • The delivery object in version 3 only allowed for very limited functionality when working with deliveries. Enhancements added to the delivery object in version 4 include the following:
    • The ability to add and read the from name used in a delivery.
    • The ability to add and read the from email address used in the delivery.
    • The ability to enable sender authentication for a delivery.
    • The ability to enable reply tracking for a delivery.
    • The ability to specify a reply-to address.
    • The ability to associate a delivery with a specific automated message rule for reporting purposes.
    • The ability to specify an array of API fields and data that can be substituted into the message used in the delivery.
  • When reading a delivery, version 4 returns much more data regarding the performance of the delivery. NOTE: In version 3, separate function calls were required to retrieve individual pieces of delivery related performance data (readOpens, readReplies, readUpdates, etc.). With version 4, you can find out:
    • The number of times the delivery has been sent.
    • The number of successful deliveries.
    • The number and specific type of hard and soft bounces.
    • Opens data (unique, average, and total).
    • Click data (unique, average, and total).
    • Conversion data (unique, average, and total).
    • Revenue generated.
    • The number of survey responses.
    • The number of forwards-to-a-friend.
    • The number of contact updates.
    • The number of unsubscribes via manage preferences.
    • The number of contacts that were lost (made inactive) by complaining via an ISP feedback loop or the applications complaint system.
    • The number of contacts lost as a result of the delivery.
    • The number of contacts lost as a result of bounces.
    • Various rates (delivery, open, click, click-through, conversion, bounce, complaint, and contact loss).
    • Various social sharing data (total social shares, total social views, per social network shares, per social network social views) for deliveries that use social sharing links. We currently provide support for Facebook, Twitter, MySpace, LinkedIn, and Digg social sharing links.
  • Version 4 includes much more data when reading a segment object. The segment object returned in version 4 includes:
    • The id assigned to the segment.
    • The name assigned to the segment.
    • The rules which define the segment.
    • The last time the segment was updated.
    • The current count of active contacts on the segment.
  • Version 4 includes convenience functions for removing specific contacts from lists using a single call, and for completely removing all contact from the list. These functions are removeFromList and clearLists.
  • In version 3, there was a readNext function used to iterate over the Read Cache and return subsequent batches of the result set. In version 4, read calls have a pageNumber parameter which will retrieve the next "batch" of objects. This reduces the number of calls you need to make.
  • Version 4 includes the following convenience functions which allow you to subsequently add, and or update contacts and delivery groups: addOrUpdateContacts, and addOrUpdateDeliveryGroups. If the contact or delivery group exists, it is updated. If it is new, it is created.
  • Version 4 allows you to add, read, update, and delete automated message rules using the unique id assigned to the messageRuleObject, rather than a handle that must be defined in the web application.