Introduction

This documentation will help you to understand and use the Inxmail Professional REST API. In this introductory chapter you will get a high level overview of the Inxmail Professional ecosystem and you will learn how to use this documentation.

About Inxmail Professional

This chapter will introduce you to Inxmail Professional and will give you an overview of the basic concepts in use. You will also learn which kinds of systems are integrated with Inxmail Professional and which workflows this API provides as of today.

Inxmail Professional in a nutshell

Inxmail Professional is an email marketing solution developed by Inxmail GmbH.

The purpose of Inxmail Professional is to send highly personalized emails to recipients by providing the ability to enrich the recipient meta data with custom data like gender, interests, date of birth or pretty much anything you can imagine.

Using this meta data, you can personalize the mailing content in various ways, including text fragments bound to certain conditions or completely different content provided by third party systems using a feature called content include.

It is also possible to use the data to build target groups, thus giving you the ability to send completely different mailings to different target groups, hence further improving the relevance of the content to the recipient.

Inxmail Professional uses a mailing list based approach to organize recipients. A mailing list is a subset of the recipients known to the system to whom you want to send a specific mailing.

Once you have created a mailing, there are various modes of dispatch available:

  • Start the dispatch immediately

  • Schedule the mailing to be dispatched at a certain point in time

  • Create a trigger mailing which is dispatched in correspondence to an event, like the recipients birthday

When using our hosted solution, the emails are dispatched via our white listed mail servers to guarantee as much visibility to the recipient as possible.

After the mailing has been sent to the recipients, you might be interested in its performance. Inxmail Professional provides you with various performance indicators out of the box, including:

  • The opening rate: tells you how many recipients opened the email

  • The click rate: tells you how many recipients clicked on a (certain) link in the email

  • The click to opening rate: tells you how many of the recipients who opened the email, also clicked a link in the email

In addition, Inxmail Professional keeps track of recipient unsubscriptions from the mailing list in direct response to the mailing. These unsubscriptions are stored per mailing list and will automatically prohibit any dispatch to the recipient from that list.

A related topic, bounces, are also covered by Inxmail Professional. Bounces occur when an email can not be forwarded to a recipient by a mail daemon. In this case, the daemon responds with an auto generated message, called a bounce.

Inxmail Professional distinguishes hard and soft bounces. A hard bounce is a permanent error, like an email address not known to the target SMTP server. A soft bounce, on the other hand, is a temporary issue, like a mail box which exceeded the quota. Inxmail Professional automatically excludes any recipient for whom a hard bounce was received from any further dispatch, irrespective of the mailing list.

With all these features, Inxmail Professional is your one-stop solution for relevant and compliant email marketing.

For more information on Inxmail Professional, please refer to the Inxmail Professional User Manual, which is downloadable through the Inxmail Community website.

Integrating third party products

We believe that integration with third party products is a very important asset and therefore strive for easy integration with all kinds of systems. Inxmail Professional already has a portfolio of many integrations to various kinds of third party products, including:

  • Online Shops

  • Customer Relationship Management (CRM) systems

  • Enterprise Resource Planning (ERP) systems

  • Web tracking systems

  • Content management systems

  • Social media platforms

While most of these integrations are written using the Inxmail Professional SOAP/Hessian API, we aim to provide you with this powerful new REST API to ease the creation of integrations with all kinds of third party systems and custom tools.

Basic workflows when using the REST API

The most basic workflow is synching recipients with a third party system. This is the case when Inxmail Professional is not the primary system to store and organize customer information but rather the tool for designing and dispatching email marketing campaigns.

For more information on how to synch recipients between Inxmail Professional and third party systems, see chapter Recipient Import.

How to use this documentation

This documentation is split up into two major parts. First there is a general section, explaining the basic concepts of the REST API, like base URL, status codes and more. After that you will find the second major part, which consists of multiple chapters each explaining one of the Inxmail Professional entities accessible through the REST API and the actions which can be performed on them.

Each of these chapters is self contained and encompasses all the information regarding the entity described. The entity chapters adhere to the following structure:

  • Description of the domain concept the entity represents

  • All possible actions available on the entity

    • Pattern for the request (HTTP Verb + URL Pattern)

    • Description of what the action does

    • Description of the path and query parameters available

    • For POST, PUT and PATCH Requests: Description of the request entity structure

    • Description of the response entity structure

    • Description of the available links (except self, next or previous links, which are already described in chapter Hypermedia)

    • Sample request

    • Sample response

While we aim to explain entities to a point a developer can use the REST API productively, further information about entities can be found in the Inxmail Professional User Manual, which is downloadable through the Inxmail Community website.

Downward compatibility guidelines

Introduction

The Inxmail Professional REST API makes it possible to control and use large parts of the Inxmail Professional range of functions via REST API. Since Inxmail Professional is constantly evolving, permanent static equilibrium of the whole REST API cannot be guaranteed. Therefore, the REST API Downward Compatibility Guidelines should ensure the greatest possible predictability when developing integrations.

REST API Versions

Inxmail always offers just one current, stable REST API version. The various REST API versions differ through the version number in the URL, for example,

/v1/endpoint

Duration of REST API version maintenance

Inxmail seeks long-term collaboration with integrators and is aware of the time and efforts that may be involved when REST APIs change. Taking stability, cost effectiveness, frequency of use and innovation into consideration, decisions are made regularly regarding supported REST API versions. Changes to the maintenance status of a REST API version will be communicated in good time. This means that Inxmail is unable to make any firm promises to maintain older REST API versions.

Table 1. Current maintenance status for each REST API version

Version

Maintenance

/v1/

Stable - is being developed, maintained and supported

Current REST API Version - Guarantees and possible changes

For the current REST API version, which is identified as stable, the following rules will be followed during further development and serve REST API users and integrators as guidelines for the most compatible and future-proof use of the REST API. The possible functional changes in the REST API version as listed should not therefore cause any problems in integrations.

Table 2. Requests
Guaranteed functionality Possible changes in functionality

  • Existing request parameters and their meaning

  • Existing parameter values of ‘enumerated sets of values’ and meaning of values

  • Validations do not become stricter

  • Inxmail may add optional request parameters

  • Inxmail may add new values for existing parameters (extension of ‘enumerated sets of values’)

  • Inxmail may add optional HTTP request headers

  • Inxmail may add new resources/endpoints

  • Inxmail may mark existing URLs of resources/endpoints as deprecated and redirect them to the new URL

  • Inxmail may add new supported media types
Table 3. Responses
Guaranteed functionality Possible changes in functionality

  • Existing response fields and their meaning

  • Meaning of existing values of ‘enumerated sets of values’

  • Inxmail may add new fields in responses

  • Inxmail may remove values for existing ‘enumerated sets of values’

  • Inxmail may add new values for existing ‘enumerated sets of values’ if this has been documented explicitly for a field

  • Inxmail may add optional HTTP request headers

  • Inxmail may add support for new additional transfer formats (for example, CSV) to existing resources, as long as this is requested explicitly in a request via the corresponding media type (for example: text/csv)

New REST API versions

Inxmail will be very conservative when it comes to assigning new REST API versions. The following changes to existing REST API functionality will result in a new REST API version.

Requests

  • Change to existing request parameters or their meaning

  • Change to existing parameter values of ‘enumerated sets of values’ or meaning of the values

  • Validations become stricter

Responses

  • Change to existing response fields or their meaning

  • Change to the meaning of existing values of ‘enumerated sets of values’

Fair use policy

Inxmail Professional REST API is not generally subject to any use restrictions provided there is fair use. If it is subject to highly intensive use, Inxmail reserves the right to agree a suitable usage rule for both sides.

By normal use of the REST API, Inxmail understands a use that does not exceed the standard rate limit of 600 requests per minute. If your application requires a higher limit, please contact us. In principle, an increase in the rate limit is possible.