Transitioning from RPC API to REST API

Hello dear reader,

This document is a starter document to transition your Inxmail integration from RPC API to the REST API. Main points to consider are included in this document. However, this document is not a replacement to the actual API documentations.

You are probably reading this document because you are still using the RPC API, also called SOAP API, of Inxmail Professional and you want to transition to the REST API.

This document starts explaining the fundamental differences, and will then give you details about specific resources and how they are handled.

First, be aware that you can still access the RPC documentation through this page: https://help.inxmail.com/de/content/xpro/home_api.htm

This document does not cover the Inxmail Commerce REST API at all.

General information

System Overview

To help you a bit to understand our new APIs, let's see what systems are working in the background and how their APIs relate to each other. If you have been with Inxmail for a long time you have been just with Inxmail Professional (we ignore Inxmail Commerce for this document). In the recent years we also introduced Inxmail New Xperience, which is built on top of Inxmail Professional. From the perspective of a common user, you would open the old Java client to interact with Inxmail Professional directly, while the Inxmail New Xperience consists of a web frontend and its own backend. Both Inxmail Professional and Inxmail New Xperience feature their own REST APIs. When talking about transitioning away from the Inxmail Professional RPC API we mean that most likely you want to move functionality to the Inxmail Professional REST API, however in some cases you would be right to use the Inxmail New Xperience REST API. The vast majority of endpoints can be found in the Inxmail Professional REST API.

Inxmail Professional REST documentation: https://apidocs.inxmail.com/xpro/rest/v1/ Inxmail New Xperience REST documentation: https://apidocs.inxmail.com/xnew/rest/v1/

REST API comes without a wrapper

While with the RPC API you could use one of our wrappers which are written in Java, C# and PHP, with REST you have to directly use REST. This shouldn't be much of a problem since many libraries will support you using REST.

We will also soon provide an Open API specification. For specific value restrictions the above linked documentation will have more details.

Authentication

Inxmail Professional REST API is available through two base URLs. As a customer of the Inxmail Platform, you can use the Inxmail Platform base URL, which provides the latest authentication mechanism. If you are not an Inxmail Platform customer, you have to continue using the Inxmail Professional base URL.

Inxmail Platform base URL: https://{space-alias}.api.inxmail.com/rest/v1 Inxmail Professional base URL (deprecated): https://api.inxmail.com/{alias}/rest/v1

Credentials:

To obtain credentials for the Inxmail Platform base URL, please follow the steps described in the Online Help - Create API credentials. If you require credentials for the Inxmail Professional base URL, please contact our support team directly.

Note: Credentials for the Inxmail Professional base URL cannot be used with the Inxmail Platform base URL.

Usage Example:

Inxmail Platform

GET https://{space-alias}.api.inxmail.com/rest/v1/lists Authorization: Basic {api-key} {secret}

Inxmail Professional

curl -u 'clientid:secret' -H 'Accept: application/hal+json' 'https://api.inxmail.com/customer/rest/v1'

The RPC API was stateful, the REST APIs are stateless, no more Sessions

In the RPC API, if you requested a collection of some objects, the server would create a snapshot with the IDs that belong to that collection. You could then iterate over the collection and get its content. These snapshots are held in a session, which was created by logging into the RPC API. Because the snapshots only hold the IDs of the contained objects, the full objects are only loaded on demand live from the database. This means your collection will have exactly those objectes that match your request at the time you created the collection request initially, however the objects themselves will be loaded live on request. The contained object may fail to load properly, if they have been deleted in the meantime.

With the REST API there is no more session and therefore no more state. Every request goes to the data on the database which reflects the current state.

When you transition from RPC to REST this difference in behaviour may cause you to think about your reimplementation. From a domain object perspective the REST API often is a drop in replacement for the RPC API. However from a technology perspective you need to consider that you will now get live data from the database instead of iterating over a snapshot of IDs.

Traversing through Result Sets and Collections

In the RPC API retrieving multiple objects in a single request returned a Result Set. It was an iterable object, and you could traverse it with its methods. In the REST API retrieving multiple objects in a single request returns a collection. It's a JSON containing multiple objects, and the JSON will contain links to traverse the collection. Collections are sorted by ID, ascending by default. Some collection endpoints do allow for ordering in descending order starting with the object with the highest ID. At this moment only sorting by ID is available. To narrow down results several collection endpoints provide filtering methods, for example name or date filters. Filters typically can be combined, unless noted otherwise.

Information regarding specific features

Switching from the Batch Channel in the RPC API

One frequently used feature in the RPC API is the Batch Channel. It is a mechanisme to mass edit recipient data. In The REST API we do not have a drop in replacement for this functionality. So how do you get new recipients into the system with the REST API? The Inxmail Professional REST API has import features for recipients, which should cover most use cases. For one time imports you can use the recipient import or its variant the advanced recipient import. We also have an import automation where you can setup an import once, and it will then automatically and continuosly import recipients from your SFTP server.

Recipient Import: https://apidocs.inxmail.com/xpro/rest/v1/#recipient-import

Advanced Recipient Import: https://apidocs.inxmail.com/xpro/rest/v1/#advanced-recipient-import

Import Automation: https://apidocs.inxmail.com/xpro/rest/v1/#import-automation

One thing to note here, if you want a history of your imports, or additional detailed information about past imports, there is a set of endpoints in the normal recipient import which is also used for advanced recipient import and import automation. See the following:

Recipient import history: https://apidocs.inxmail.com/xpro/rest/v1/#_retrieve_import_execution_history_collection

Imported files: https://apidocs.inxmail.com/xpro/rest/v1/#_retrieve_import_files_collection

Import errors: https://apidocs.inxmail.com/xpro/rest/v1/#_retrieve_import_errors_collection

Introduction to the REST API reporting features

In the RPC API you can get both raw data and clearly defined reports. With the REST API the predefined reports are gone, you will retrieve raw data and use them to create your own reports. For those of you who already relied on raw data before, there is no real change for you in the REST API. Users of the predefined reports need to consider how to build these reports with the REST API. The REST API has a few endpoints that provide meaningful compositions of data, which can be a good foundation of a report.

Sending statistics: https://apidocs.inxmail.com/xpro/rest/v1/#sending-statistics

Response statistics: https://apidocs.inxmail.com/xpro/rest/v1/#response-statistics

Mailings in the REST API

With the RPC API you had access to the Mailings in Inxmail Professional. There are some slight changes with the REST API. With the Inxmail Professional REST API you still have access to the same mailings, however there are also Inxmail New Xperience mailings, which are only accessible through the Inxmail New Xperience REST API.

Inxmail New Xperience mailings are the mailing objects in Inxmail New Xperience, a counterpart mailing will be created in Inxmail Professional upon sending an Inxmail New Xperience mailing. Please consult the REST documentation, but also the user documentation for Inxmail New Xperience.

Inxmail New Xperience user documentation: https://help.inxmail.com/de/content/xnew/xnew_home.htm

In the Inxmail Professional REST API you can access Mailings with different endpoints. There is a common 'mailings' endpoint which will give access to all mailings of all types. The fields contained in the JSON are rather limited to those which are common accross all mailing types. Be aware that there is a difference in the naming: In the RPC API the MailingManager gave access standard mailings, these are now called regular mailings in the REST API.

For each mailing type, the REST API also has specific endpoints to work with these mailings.

Inxmail Professional REST API Mailings endpoint: https://apidocs.inxmail.com/xpro/rest/v1/#mailings (replaces GeneralMailingManager from RPC API)

Inxmail Professional REST API Regular Mailings endpoint: https://apidocs.inxmail.com/xpro/rest/v1/#regularmailings (replaces MailingManager from RPC API)

Inxmail Professional REST API Split-Test-Mailings endpoint: https://apidocs.inxmail.com/xpro/rest/v1/#splittestmailings (replaces SplitTestMailingmanager from the RPC API)

Inxmail Professional REST API Trigger-Mailings endpoint: https://apidocs.inxmail.com/xpro/rest/v1/#triggermailings (replaces TriggerMailingManager from the RPC API)

RPC API Features not available in the REST API

Some features have been available in the RPC API but are currently not available in the REST API, or may never be available in the REST API.

Xslt HTML Mailings and MailingTemplateManager

In Inxmail Professional special templates to produce mailings had been available, these were called XSLT HTML Mailings, because of the technology they were based on. These templates will eventually be phased out and are not available through REST. The related MailingTemplateManager also does not and will not have a replacement in the REST API.

SplitTestManager

Inxmail New Experience uses separate code from the original split tests in Inxmail Professional. For now split tests are not available through the REST API, the future of this functionality in a REST context is undecided. Split-Test-Mailings are available through the REST API however.

TransformationManager

While data sources are already available in the REST API, the related transformations are not yet available through REST. They will probably become available in the future.

PDF Datasources have limited support in the REST API.

Datasources: https://apidocs.inxmail.com/xpro/rest/v1/#datasources

ResourceManager

The RPC API's ResourceManager is not yet available through the REST API. It may become available in the future.

WebpageManager

The RPC API's WebpageManager is not available through the REST API. It will most likely not become available through the REST API.

TemporaryMailSender

While the RPC API's TemporaryMailSender does have a replacement functionality, the details how it works is different. Please check the manual.

Send a single mail: https://apidocs.inxmail.com/xpro/rest/v1/#send-a-single-or-mass-mailing

Getting further help

This short guide is not a replacement of the complete documentation, rather it is a pointer for the main points to consider when moving to the REST API. Please consult the documentation to get detailed answers. If that doesn't help, get in contact with your Inxmail or Inxmail partner contact.